Skip to main content
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:

​
Connection setup

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.

​
Adding task context

To use Task-Based Access Control, include a task token in your requests:
  1. Create a task session via the Task Sessions API
  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: 
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

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
MCP is disabled for this project. Enable it in Project Settings.
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
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.
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