Reference

API Reference

Complete reference for all Agent Dojo MCP API endpoints. Base URL: https://api.agentdojo.dev/mcp

Authentication

All endpoints require an API key passed via the X-API-Key header unless noted otherwise.

curl https://api.agentdojo.dev/mcp/servers \
  -H "X-API-Key: your-api-key"

The core JSON-RPC 2.0 endpoint for MCP clients (Claude Desktop, Cursor, etc.).

Method	Path	Description	Rate Limit
POST	/{slug}	JSON-RPC 2.0 protocol endpoint (initialize, tools/list, tools/call, resources/, prompts/, ping)	100/min

Supports methods: initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, ping

Method	Path	Description	Rate Limit
POST	/servers	Create a new MCP server	20/min
GET	/servers	List all servers for the authenticated project	60/min
GET	/servers/{id}	Get server details with tools and credential status	60/min
DELETE	/servers/{id}	Delete an MCP server	20/min
POST	/servers/{server_id}/tools	Add tools to a server	30/min
PATCH	/servers/{server_id}/tools/{tool_id}	Update a server tool's credential or settings	30/min
DELETE	/servers/{server_id}/tools	Remove tools from a server	30/min

Method	Path	Description	Rate Limit
POST	/toolkits	Register a new toolkit	10/min
GET	/toolkits	List registered toolkits	100/min
GET	/toolkits/{id}	Get toolkit details	100/min
PUT	/toolkits/{id}	Update a toolkit	50/min
DELETE	/toolkits/{id}	Delete a toolkit	20/min

Method	Path	Description	Rate Limit
POST	/tools	Register a new tool	50/min
GET	/tools	List available tools	100/min
POST	/tools/list	List tools (MCP-compatible)	100/min
POST	/tools/call	Call a tool with arguments	1000/min

Method	Path	Description	Rate Limit
POST	/resources	Register a new resource	50/min
POST	/resources/list	List available resources	100/min
POST	/resources/read	Read content from a resource	500/min
POST	/resources/subscribe	Subscribe to resource changes	100/min
POST	/resources/unsubscribe	Unsubscribe from resource changes	100/min
POST	/resources/subscriptions	List active resource subscriptions	100/min

Method	Path	Description	Rate Limit
POST	/prompts	Register a new prompt	50/min
POST	/prompts/list	List available prompts	100/min
POST	/prompts/get	Get a prompt with arguments	500/min

Method	Path	Description	Rate Limit
POST	/credentials	Create a new credential	30/min
GET	/credentials	List credentials for the current project	100/min
DELETE	/credentials/{id}	Delete a credential	30/min
GET	/providers	List authentication providers	100/min

Method	Path	Description	Rate Limit
POST	/oauth/init	Initialize OAuth flow	50/min
POST	/oauth/build-auth-url	Build OAuth authorization URL	100/min
GET	/oauth/callback	Handle OAuth callback	100/min
POST	/oauth/exchange-token	Exchange code for access token	50/min
POST	/oauth/refresh-token	Refresh OAuth access token	100/min
GET	/oauth/status	Check OAuth flow status	100/min
POST	/oauth/cancel	Cancel OAuth flow	50/min

Method	Path	Description	Rate Limit
POST	/subscribe	Subscribe to webhook events	-
POST	/unsubscribe	Unsubscribe from webhook events	-
GET	/subscriptions	List active subscriptions	-
POST	/subscription/update	Update a subscription	-
POST	/webhooks/list	List available webhook events	100/min
POST	/webhooks/{subscription_id}	Receive webhook from external service	-

Method	Path	Description	Rate Limit
GET	/health	Health check (no auth required)	100/min
POST	/initialize	Initialize MCP connection (standalone)	10/min

HTTP Status	Meaning
200	Success (also used for JSON-RPC errors in protocol endpoint)
202	Accepted (notifications, no response body)
400	Bad request (missing or invalid parameters)
401	Unauthorized (missing, invalid, or expired API key)
404	Not found (server, tool, resource, or credential not found)
429	Rate limit exceeded
500	Internal server error

When using the protocol endpoint (POST /mcp/{slug}), errors are returned in JSON-RPC format with HTTP 200:

Code	Meaning
-32600	Invalid request (bad JSON-RPC format, invalid slug, invalid API key)
-32601	Method not found
-32602	Invalid params (tool not found, missing required arguments)
-32603	Internal error (tool execution failure, no function config)

Example JSON-RPC error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Tool 'unknown-tool' not found in this endpoint"
  }
}