Connect an Agent

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 in the Devctrl console
At least one MCP server registered with tools
An identity with a credential
An active policy release

Connection setup

Claude Desktop
Claude Code
MCP Inspector
Custom agent

Add Devctrl as an MCP server in your Claude Desktop configuration:

{
  "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.

Configure Devctrl as a remote MCP server in your Claude Code settings:

{
  "mcpServers": {
    "devctrl": {
      "url": "https://gateway.devctrl.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CREDENTIAL_SECRET"
      }
    }
  }
}

Use the MCP Inspector to test the connection interactively:

Open the Inspector
Set Transport Type to Streamable HTTP
Set URL to https://gateway.devctrl.ai/mcp
Add header Authorization: Bearer YOUR_CREDENTIAL_SECRET
Click Connect

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

Use any MCP SDK to connect. Here’s an example with the MCP TypeScript SDK:

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" },
});

Adding task context

To use Task-Based Access Control, include a task token in your requests:

Create a task session via the Task Sessions API
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:

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

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

403 Forbidden — MCP not enabled

MCP is disabled for this project. Enable it in Project Settings.

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

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.

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

Get Started

Core Concepts

Console Guide

Gateway

Policies

Connect an Agent

Prerequisites

Connection setup

Adding task context

Troubleshooting

​Prerequisites

​Connection setup

​Adding task context

​Troubleshooting

Prerequisites

Connection setup

Adding task context

Troubleshooting