Servers

Create a Server

Create a new MCP server with toolkits and start serving tools to AI clients.

Creating a Server

Create a new server by sending a POST request to /mcp/servers.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name for the server
`slug`	string	No	URL-friendly identifier. Auto-generated from name if not provided.
`description`	string	No	Optional description of the server's purpose
`toolkits`	array	No	Array of toolkit configurations with toolkit_id and credential_id

Basic Example

Create a simple server with a name and description:

curl -X POST https://api.agentdojo.dev/mcp/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Notification Server",
    "description": "Server for sending push notifications"
  }'

Response:

{
  "id": 15,
  "slug": "my-notification-server",
  "name": "My Notification Server",
  "description": "Server for sending push notifications",
  "url": "https://api.agentdojo.dev/my-notification-server",
  "api_key": "sk_server_abc123...",
  "is_active": true,
  "request_count": 0,
  "last_used_at": null,
  "created_at": "2026-01-15T10:30:00.000Z"
}

Slug Rules

Slugs follow these rules:

Only lowercase letters, numbers, and hyphens are allowed
Auto-generated from the server name if not explicitly provided
Must be unique across all servers in your project

# These are valid slugs:
"my-server"
"notifications-v2"
"prod-tools-2026"

# These are invalid:
"My Server"       # No uppercase or spaces
"my_server"       # No underscores
"my.server"       # No dots

Adding Toolkits at Creation

You can attach toolkits when creating the server by providing a toolkits array. Each entry requires a toolkit_id and a credential_id to authenticate with the toolkit's service.

curl -X POST https://api.agentdojo.dev/mcp/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pushover Alerts",
    "slug": "pushover-alerts",
    "description": "Server with Pushover notification tools",
    "toolkits": [
      {
        "toolkit_id": 32,
        "credential_id": 52
      }
    ]
  }'

After Creation

Your server is immediately available at the returned URL. Connect via the MCP protocol to start using tools. Here is an example flow: create a server with the Pushover toolkit, then immediately call initialize to establish a session.

1. Create the server

curl -X POST https://api.agentdojo.dev/mcp/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pushover Alerts",
    "toolkits": [{"toolkit_id": 32, "credential_id": 52}]
  }'

# Response includes:
# "url": "https://api.agentdojo.dev/pushover-alerts"

2. Initialize the MCP connection

curl -X POST https://api.agentdojo.dev/pushover-alerts \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "my-client",
        "version": "1.0.0"
      }
    }
  }'