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

# Register MCP Servers

> Connect upstream MCP tool servers so agents can discover and call tools through the gateway.

MCP servers are the upstream tool providers that your agents interact with through the Devctrl gateway. Register a server to make its tools available in your project.

## Add from the catalog

1. Navigate to **Tools** in your project sidebar
2. Click **Register MCP server**
3. Select a service from the catalog — **GitHub**, **Linear**, or **Notion**

For **GitHub** and other API-key services, you'll be asked for your token. The endpoint URL and header format are pre-configured.

For **Linear**, **Notion**, and other OAuth services, you'll be redirected to authorize access after registering.

## Add a custom server

If your MCP server isn't in the catalog, click **Enter a custom URL** and provide:

| Field            | Required | Description                               |
| ---------------- | -------- | ----------------------------------------- |
| **Endpoint URL** | Yes      | The MCP server's StreamableHTTP endpoint  |
| **Headers**      | No       | Authentication headers (API keys, tokens) |

Devctrl tests the connection and discovers available tools automatically.

## Authentication methods

<Tabs>
  <Tab title="Header-based">
    Add static headers that the gateway injects into every request to this server.

    Common patterns:

    * `Authorization: Bearer <api-token>`
    * `X-API-Key: <key>`
    * Custom headers required by your tool server

    Headers are encrypted at rest. The plaintext is never stored in the database.
  </Tab>

  <Tab title="OAuth">
    Configure OAuth for servers that require token-based authentication with refresh support.

    | Field              | Description                                                          |
    | ------------------ | -------------------------------------------------------------------- |
    | **Client ID**      | OAuth client identifier                                              |
    | **Client Secret**  | OAuth client secret (encrypted at rest)                              |
    | **Token endpoint** | URL for token refresh (e.g., `https://auth.example.com/oauth/token`) |

    The gateway handles the full OAuth lifecycle:

    * Automatically refreshes access tokens before they expire
    * Retries with a fresh token on 401 responses
    * Encrypts and persists refreshed tokens to the database
  </Tab>
</Tabs>

## Tool discovery

After registering a server, Devctrl discovers the tools it exposes. Tools appear in the **Tools** section of your project. Each tool has:

* **Name** — the tool identifier used in MCP `tools/call` requests
* **Description** — what the tool does
* **Input schema** — the expected arguments

Tools are automatically synced from the upstream server.

## Multiple servers

You can register multiple MCP servers in a single project. The gateway routes each tool call to the correct server based on the tool's registration.

```
Project: customer-support
├── jira-server     → get_issue, create_issue, update_issue
├── linear-server   → list_projects, create_issue, add_comment
└── stripe-server   → get_customer, process_refund, list_invoices
```

Each server can use a different authentication method.

## Next steps

<CardGroup cols={2}>
  <Card title="Manage tools" icon="wrench" href="/console/manage-tools">
    View and configure the tools discovered from your MCP servers.
  </Card>

  <Card title="Create identities" icon="id-card" href="/console/create-identities">
    Create agent identities to authenticate with the gateway.
  </Card>
</CardGroup>