> ## 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.

# Connect an Agent

> Point any MCP-compatible AI agent at the Devctrl gateway.

Any agent that speaks the MCP protocol can connect to Devctrl. The gateway exposes a standard MCP StreamableHTTP endpoint at `/mcp`.

## Prerequisites

Before connecting an agent, make sure you have:

* A [project](/console/projects) in the Devctrl console
* At least one [MCP server registered](/console/register-mcp-servers) with tools
* An [identity with a credential](/console/create-identities)
* An [active policy release](/console/publish-policies)

## Connection setup

<Tabs>
  <Tab title="Claude Desktop">
    Add Devctrl as an MCP server in your Claude Desktop configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "devctrl": {
          "url": "https://gateway.devctrl.ai/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_CREDENTIAL_SECRET"
          }
        }
      }
    }
    ```

    Claude will discover tools from the gateway automatically via `tools/list`.
  </Tab>

  <Tab title="Claude Code">
    Configure Devctrl as a remote MCP server in your Claude Code settings:

    ```json theme={null}
    {
      "mcpServers": {
        "devctrl": {
          "url": "https://gateway.devctrl.ai/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_CREDENTIAL_SECRET"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="MCP Inspector">
    Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to test the connection interactively:

    1. Open the Inspector
    2. Set **Transport Type** to **Streamable HTTP**
    3. Set **URL** to `https://gateway.devctrl.ai/mcp`
    4. Add header `Authorization: Bearer YOUR_CREDENTIAL_SECRET`
    5. Click **Connect**

    The Inspector handles the MCP protocol handshake automatically. You can browse tools and make test calls from the UI.
  </Tab>

  <Tab title="Custom agent">
    Use any MCP SDK to connect. Here's an example with the MCP TypeScript SDK:

    ```typescript theme={null}
    import { Client } from "@modelcontextprotocol/sdk/client/index.js";
    import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

    const transport = new StreamableHTTPClientTransport(
      new URL("https://gateway.devctrl.ai/mcp"),
      {
        requestInit: {
          headers: {
            Authorization: "Bearer YOUR_CREDENTIAL_SECRET",
          },
        },
      }
    );

    const client = new Client({ name: "my-agent", version: "1.0.0" });
    await client.connect(transport);

    // List available tools
    const tools = await client.listTools();

    // Call a tool
    const result = await client.callTool({
      name: "get_issue",
      arguments: { issue_id: "TICKET-123" },
    });
    ```
  </Tab>
</Tabs>

## Adding task context

To use [Task-Based Access Control](/concepts/task-based-access-control), include a task token in your requests:

1. Create a task session via the [Task Sessions API](/gateway/task-sessions)
2. Add the `X-Task-Token` header to your MCP requests

In the MCP Inspector, add `X-Task-Token: YOUR_TASK_TOKEN` as an additional header alongside your `Authorization` header.

In code, include the header in your transport configuration:

```typescript theme={null}
const transport = new StreamableHTTPClientTransport(
  new URL("https://gateway.devctrl.ai/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer YOUR_CREDENTIAL_SECRET",
        "X-Task-Token": "YOUR_TASK_TOKEN",
      },
    },
  }
);
```

## Troubleshooting

<Accordion title="401 Unauthorized">
  The bearer token is invalid, expired, or revoked. Check that:

  * The credential secret is correct (not the credential ID)
  * The credential hasn't been revoked in the console
  * The credential hasn't expired
</Accordion>

<Accordion title="403 Forbidden — MCP not enabled">
  MCP is disabled for this project. Enable it in **Project Settings**.
</Accordion>

<Accordion title="403 Forbidden — Policy denied">
  The policy engine denied the tool call. Check:

  * The active policy release in the console
  * The identity's labels match what the policy expects
  * If using task tokens, ensure the task context is correct
  * View the specific denial reason in **Executions**
</Accordion>

<Accordion title="429 Too Many Requests">
  Rate limit exceeded. The response includes which level was hit:

  * **Session**: your agent is making too many calls. Space out requests.
  * **Project**: all agents in this project have exceeded the project limit.
  * **Global**: the gateway's global limit was hit.
</Accordion>

<Accordion title="Tool not found">
  The tool doesn't exist or isn't visible to this identity. Check:

  * The tool is registered under an MCP server in the project
  * The identity's `allowedTools` list includes this tool (or is unrestricted)
  * The upstream MCP server is healthy
</Accordion>