MCP server

Beta

The Treble MCP server is in beta. Tools and endpoints may change.

The Treble MCP server lets AI assistants that support the Model Context Protocol (MCP) look things up in the Treble SDK documentation and your Treble libraries while they help you write SDK code. It builds on the instruction files for AI coding assistants: it gives the assistant the same instructions and skills, and stays up to date by itself, while the files have to be downloaded again after SDK updates. If your assistant supports MCP, use the server instead of the files.

The server is read-only for now. It can search the documentation and API reference, estimate token costs, and search your libraries. It never starts simulations or spends tokens. More abilities will be added over time.

Turn MCP on for your organization

An organization administrator turns MCP on or off with the Allow AI assistants to connect to Treble (MCP) switch on the MCP servers page. While it's off, no assistant in the organization can connect.

Choose a server

---

Built-in servers

Server URL	What the assistant can use
https://mcp.treble.tech/mcp/docs	The SDK documentation and API reference, agent instructions, and token estimates.
https://mcp.treble.tech/mcp/read-only	Everything above, plus read access to your geometry, geometry component, material and source directivity libraries.

Use /mcp/docs if the assistant only needs to help you write code. Use /mcp/read-only if you want it to find real geometries, materials or directivities for you.

Your organization's servers

Organization administrators can create MCP servers that can only read the libraries they choose, for example only materials. Open the Servers tab on the MCP servers page of the management portal, click Create server, give it a name and select the libraries. Its URL looks like https://mcp.treble.tech/mcp/<organization>/<name>.

• Share with everyone in the organization is ticked by default: everyone in the organization can see and use the server. Untick it to keep the server for administrators only. Each person still signs in as themselves and only sees what their own account can see.
• Users who aren't administrators can't create servers. They use the built-in servers and the servers their administrators shared.
• It works with OAuth and with MCP API keys. A key created for the server gets the server's libraries.
• An organization administrator, or the person who created the server, can delete it. Clients connected to a deleted server stop working, and its API keys are revoked.

Choose how to sign in

---

There are two ways to authenticate. Both act as you: the assistant only sees what your Treble account can see.

• OAuth (sign in with your Treble account). You add the server URL to the assistant and sign in in your browser. The assistant stores and refreshes the access token for you.
• MCP API key. You create a key on the My API keys tab of the MCP servers page in the management portal and paste it into the assistant's configuration. The assistant sends the key with every request.

	OAuth	MCP API key
Setup	Add the URL and sign in. No secret to copy.	Create a key, then add it to the configuration as a header.
Secret to look after	None. Tokens are short-lived and stored by the assistant.	The key. Anyone who has it can use it until it expires or is revoked.
Clients	Clients with MCP OAuth support, such as Claude, Claude Code and Visual Studio Code.	Any MCP client that can send an Authorization header, including clients without OAuth support.
Sign-in	Needs a browser sign-in, and sometimes again later.	No browser. Works on remote machines, in containers and in scripts.
Permissions	You can't choose them when you sign in. The server you connect to decides what the assistant can access, so create your own server to limit it to some libraries.	The same: each key belongs to one server and gets that server's libraries. It only works on that server's URL.
Lifetime	Until you disconnect, or your account or subscription ends.	30 days to 1 year. Rotate the key to get a new one with the same lifetime.
Revoking	Disconnect the server in the assistant.	Revoke the key on the MCP servers page. The assistant loses access within 5 minutes.

Use OAuth when you work in Claude, Claude Code or Visual Studio Code on your own computer. It is the simplest option, and there is no secret that can leak.

Use an MCP API key when the client does not support MCP OAuth, or when you can't open a browser on the machine that runs the assistant (for example over SSH, in a dev container or in CI). Either way, you limit the assistant to some libraries by connecting to a server your organization created with only those libraries.

Use a service account for shared keys. When one key is used by many people or by an automated system, for example a key in Claude's Request headers on a Team or Enterprise plan, or a key in CI, create it with a dedicated Treble user with SDK access rather than a personal account. Everyone who uses the key acts as its owner and sees what that account can see, and the key keeps working when people leave: a key stops working when its owner is disabled or leaves the organization.

Connect with OAuth

---

Claude

For claude.ai and Claude Desktop:

1. Go to Customize > Connectors, click + Add, and choose Add custom connector.
2. Enter a name, such as Treble, and the server URL, for example https://mcp.treble.tech/mcp/read-only. Click Continue.
3. Keep the authentication settings Claude detected and click Continue.
4. Under Authentication, choose Sign in when needed. Under OAuth client, choose Use Claude's published identity. Click Add.
5. Click Connect and sign in with your Treble account.
6. In a chat, enable the connector from the + button > Connectors.

On Team and Enterprise plans, an owner adds the connector for the organization, and each member then clicks Connect and signs in with their own Treble account. See Anthropic's guide to custom connectors.

Claude Code

1. Add the server:

   claude mcp add --transport http treble https://mcp.treble.tech/mcp/read-only

2. Start Claude Code and run /mcp.

3. Select treble and choose Authenticate.

4. Sign in with your Treble account in the browser window that opens.

To share the server with your team, add --scope project to the command in step 1. This saves the server in .mcp.json, which you can commit. Your sign-in isn't saved there, so each person signs in with their own account. See Claude Code MCP.

VS Code

1. Open your user mcp.json with MCP: Open User Configuration in the Command Palette. To add the server to one workspace only, open .vscode/mcp.json in that workspace instead.

2. Add the server:

   {
     "servers": {
       "treble": {
         "type": "http",
         "url": "https://mcp.treble.tech/mcp/read-only"
       }
     }
   }

3. Start the server from the editor or from the MCP servers list.

4. Sign in with your Treble account in the browser window that opens.

5. Use the Treble tools in Copilot Chat in agent mode.

See MCP servers in VS Code.

Connect with an MCP API key

---

Create a key

1. Open the MCP servers page in the management portal (MCP servers in the account menu) and go to the My API keys tab.
2. Click Create key, or click + next to a server on the Servers tab. Give the key a name that says where you'll use it, such as Laptop - Claude Code.
3. Choose the server. The key gets that server's libraries and only works on its URL. Then choose when it expires (up to 1 year).
4. Copy the key. It is shown only once. The page also shows setup snippets with the server's URL.

Keys start with trbl_mcp_. Store them like passwords. Don't commit them to a repository or paste them into a chat.

Add the key to your assistant

The examples use https://mcp.treble.tech/mcp/read-only. Replace it with the URL of the server you created the key for: a key only works on its own server.

Claude

For claude.ai and Claude Desktop:

1. Go to Customize > Connectors, click + Add, and choose Add custom connector.
2. Enter a name, such as Treble, and the server URL. Click Continue.
3. Under Authentication, choose No sign in.
4. Under Request headers, add a header named Authorization with the value Bearer <your key>. Click Add.
5. In a chat, enable the connector from the + button > Connectors.

On Team and Enterprise plans, every member uses the owner's key, so create it with a service account.

Claude Code

1. Read the key into a variable, so it isn't saved in your shell history. Run this, paste the key and press Enter. Nothing is shown while you paste.

   read -rs TREBLE_MCP_KEY

2. Add the server and clear the variable:

   claude mcp add --transport http treble https://mcp.treble.tech/mcp/read-only \
     --header "Authorization: Bearer $TREBLE_MCP_KEY"
   unset TREBLE_MCP_KEY

3. Start Claude Code and run /mcp to check that treble is connected.

The key is saved only for you, in ~/.claude.json. Don't add --scope project to the command: that writes the key into .mcp.json, which is meant to be committed.

To share the server with your team, commit this .mcp.json at the project root instead of running the commands above. Each person sets the environment variable TREBLE_MCP_KEY to their own key before starting Claude Code. If you already added a treble server with the commands above, remove it with claude mcp remove treble --scope local, because it takes precedence over the shared one. See Claude Code MCP.

{
  "mcpServers": {
    "treble": {
      "type": "http",
      "url": "https://mcp.treble.tech/mcp/read-only",
      "headers": {
        "Authorization": "Bearer ${TREBLE_MCP_KEY}"
      }
    }
  }
}

VS Code

1. Open your user mcp.json with MCP: Open User Configuration in the Command Palette, or .vscode/mcp.json in a workspace.

2. Add the server. The key isn't written in the file: VS Code asks for it and stores it securely.

   {
     "inputs": [
       {
         "type": "promptString",
         "id": "treble-mcp-key",
         "description": "Treble MCP API key",
         "password": true
       }
     ],
     "servers": {
       "treble": {
         "type": "http",
         "url": "https://mcp.treble.tech/mcp/read-only",
         "headers": {
           "Authorization": "Bearer ${input:treble-mcp-key}"
         }
       }
     }
   }

3. Start the server from the editor or from the MCP servers list, and paste your key when VS Code asks for it.

4. Use the Treble tools in Copilot Chat in agent mode.

This works in Local agent sessions only. VS Code doesn't pass servers with input variables to Copilot CLI sessions, so sign in with OAuth there instead.

Cursor

1. Set the environment variable TREBLE_MCP_KEY to your key: in your shell profile on macOS and Linux, or as a user environment variable on Windows.

2. Add the server to ~/.cursor/mcp.json in your home directory. Cursor reads the key from the variable, so it isn't written in the file.

   {
     "mcpServers": {
       "treble": {
         "url": "https://mcp.treble.tech/mcp/read-only",
         "headers": {
           "Authorization": "Bearer ${env:TREBLE_MCP_KEY}"
         }
       }
     }
   }

3. Restart Cursor, so it picks up the variable. On macOS and Linux, start it from a terminal with cursor: apps opened from the Dock or app menu don't read your shell profile.

To share the server with your team, put the same entry in the project's .cursor/mcp.json and commit it. Each person sets TREBLE_MCP_KEY to their own key. See Cursor MCP.

Other

1. Add a remote MCP server that uses the streamable HTTP transport.

2. Set its URL to the server URL.

3. Add this header:

   Authorization: Bearer <your key>

Keep the key out of files you commit. Use the client's secret storage or an environment variable if it has one.

Manage keys

The My API keys tab lists your keys with their server, when they were last used and when they expire.

• Rotate a key to replace it, for example before it expires or if it may have leaked. You get a new key with the same name, server and lifetime, shown only once. The old key stops working within 5 minutes, so update every client that uses it.
• Revoke a key as soon as you stop using it. Clients that use it lose access within 5 minutes.

Organization administrators also see an Organization API keys tab. It lists every key in the organization, and administrators can revoke any of them. Administrators can't create or rotate keys for other users, because a key is shown only to the person who creates or rotates it.

A key stops working when it expires or is revoked, when its server is deleted, or when MCP is turned off for your organization. It also stops working when its owner is disabled, loses SDK access or leaves the organization. Disabling a user doesn't revoke their keys: if the user is enabled again, keys that haven't expired work again. Revoke them on the Organization API keys tab if they shouldn't.

Troubleshooting

---

Problem	What to do
The assistant says it isn't authorized, or asks you to sign in again.	Reconnect or re-authenticate the server. With an API key, check that the key hasn't expired or been revoked, that the header is Authorization: Bearer <key>, and that the URL is the key's server. A key used on another server's URL is rejected.
The server connects, but every call fails with an access error.	Check that your Treble SDK subscription is active on the management portal, and that MCP is turned on for your organization on the MCP servers page. Only an organization administrator can turn it on.
Your organization's server URL returns "not found" (404).	Check the URL on the Servers tab of the MCP servers page. The server may have been deleted, be shared only with administrators, or MCP may be turned off for your organization.
Only documentation tools are available.	You are connected to /mcp/docs. Connect to /mcp/read-only or your organization's server.