> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.altrum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Register your organization's MCP servers in Altrum, control which tools each AI system and key can use, and use them from coding agents and applications.

MCP servers give models tools: search a ticket system, read a repository, query a database. Register them once in Altrum, and every tool call goes through the same governance as model requests: access rules, guardrails and logs.

## Register an MCP server

Owners and admins open **AI Gateway**, then **MCP servers**, and choose **Add server**. Give it:

* **Name**: letters, digits and underscores, starting with a letter. Tools are named after it, for example `github_search_issues`.
* **Address**: the server's http or https URL, for example `https://mcp.example.com/mcp`.
* **Transport**: **Streamable HTTP** or **Server-sent events**.
* **Authentication**: how Altrum connects to it.

| Authentication | Who connects |
| - | - |
| None | Nobody: the server is open. |
| Shared headers | An admin enters headers, such as an API key, once for the organization. |
| Shared sign in | An admin signs in once, straight after choosing **Add and sign in**, and the organization uses that connection. |
| Each person signs in | Each person signs in with their own account, such as their own GitHub, under **My connections**. |
| Each person enters headers | Each person enters their own key for the server under **My connections**. You name the headers and give your own values once, so Altrum can check the server takes them. |

For a server that signs people in, the client id, client secret, sign in page, token page and scopes are optional: leave them empty and Altrum finds them from the server.

Switch on **Available to every key** to let every key of the organization use the server. Otherwise give it to keys one by one, under **MCP tools** on each key.

Headers and secrets are stored encrypted and never shown again. The address and the authentication cannot change: add a new server, then delete the old one. **Edit** changes the name, the tools the server may serve, whether it is used, whether every key may use it, and replaces shared headers. **Reconnect** connects again straight away, and **Delete** removes the server and every person's connection to it.

Each server shows its state (**Connected**, **Unstable**, **Sign in again**, **Waiting for sign in**, **Off** or **Not reachable**) and the tools it has.

Servers that run as local processes are not supported. Altrum refuses addresses on private networks, and checks the address again every time it connects, so a name that later points somewhere private is refused too. Code mode, running tools without your application asking, and skipping the server's certificate check are not offered.

## Connect your own account

For servers that act as each person, open **AI Gateway**, then **My connections**. Choose **Connect**: a server you sign in to opens its own sign in page and brings you back, and a server that takes headers asks for your values. **Disconnect** removes your connection. Tool calls made with your [personal key](/ai-gateway/virtual-keys#personal-keys) then run as you. A request made with an organization or AI system key cannot use a per-person server, and **My connections** says so when you have no personal key yet.

## Choose who can use which tools

A list of servers and tools can be set at three levels. A key sees only the tools every level allows. A server that is not ticked in a list is not reachable, and leaving a server's tools empty allows every tool (`*`).

| Level | Where |
| - | - |
| The organization's own keys | **AI Gateway**, then **MCP servers**, under **Organization keys**: switch on **Limit which MCP tools these keys reach**. |
| Every key of an AI system | The AI system's **AI Gateway** tab, under **MCP tools**. |
| One key | The key's **MCP tools**, when you create or edit it. |

## Use the tools

<Tabs>
  <Tab title="Coding agents">
    Add Altrum's MCP endpoint, `https://api.altrum.ai/mcp`, to your coding agent with your personal key. The agent sees the tools your key allows, across all your organization's servers. **MCP servers** shows the setup with your organization's address under **Connect your agent**. See also [Coding agents](/ai-gateway/coding-agents).

    <CodeGroup>
      ```bash Claude Code theme={null}
      claude mcp add --transport http altrum https://api.altrum.ai/mcp --header "Authorization: Bearer your-personal-key"
      ```

      ```toml Codex CLI theme={null}
      # export ALTRUM_VIRTUAL_KEY="your-personal-key", then in ~/.codex/config.toml
      [mcp_servers.altrum]
      url = "https://api.altrum.ai/mcp"
      bearer_token_env_var = "ALTRUM_VIRTUAL_KEY"
      ```

      ```json Cursor theme={null}
      // ~/.cursor/mcp.json
      {
        "mcpServers": {
          "altrum": {
            "url": "https://api.altrum.ai/mcp",
            "headers": { "Authorization": "Bearer your-personal-key" }
          }
        }
      }
      ```

      ```json VS Code theme={null}
      // .vscode/mcp.json
      {
        "inputs": [{ "type": "promptString", "id": "altrum-key", "description": "Your Altrum key", "password": true }],
        "servers": {
          "altrum": {
            "type": "http",
            "url": "https://api.altrum.ai/mcp",
            "headers": { "Authorization": "Bearer ${input:altrum-key}" }
          }
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Your applications">
    Altrum adds the allowed tools to your chat requests. When the model asks for a tool, your application asks Altrum to run it and sends the result back to the model.
  </Tab>
</Tabs>

## When a tool cannot run

A request to `https://api.altrum.ai/mcp` without a key is refused:

```
virtual key required to access the MCP server; set one of x-alt-vk, Authorization: Bearer <key>, x-api-key, or x-goog-api-key in your MCP client config
```

A tool the key may not use is refused with status 403 and the code `mcp_tool_blocked`.

A server that works with each person's own account needs a personal key. Two answers explain what is missing, word for word:

* `<server> needs a personal key: it works with each person's own account, which a shared key does not have. Use a personal key to call it.` The tool is also left out of the list an organization or AI system key sees.
* `Your account is not connected to <server>. Connect it in Altrum under AI Gateway, My connections, then try again.`

## Governance on every call

* Tool arguments are checked by your guardrails before the tool runs, and results before they return to the model. See [Guardrails at runtime](/guardrails/at-runtime#tool-calls).
* Every call is logged: the tool, the server, who called it, how long it took and whether it worked. Arguments and results are kept only when content logging is on. See [Request logs](/ai-gateway/request-logs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.