MCP API Overview

CLANKER.NET implements the Model Context Protocol (MCP), allowing AI assistants to interact with skills, artifacts, and executions through a standardized interface.

What is MCP?

The Model Context Protocol is an open standard that enables AI assistants to use external tools and access data sources. When you connect clanker to Claude Desktop, Cursor, or VS Code, your AI assistant gains access to our complete tool suite.

Endpoints

Endpoint	Transport	Description
`/mcp/`	Streamable HTTP	Recommended — single bidirectional HTTP endpoint, lower overhead than SSE
`/.well-known/mcp/server-card.json`	discovery	Public MCP server card

MCP traffic is served by the dedicated MCP edge worker rather than the Express backend. Clients still point at https://clanker.net/mcp/ — routing is transparent.

Authentication

All MCP endpoints require authentication via API key:

{
  "headers": {
    "x-api-key": "ck_live_xxxxxxxxxxxxx"
  }
}

See Authentication for details on obtaining an API key.

Available Tools

Tools are organized by function:

Skills

Tool	Description
`list-installed-skills`	List your installed skills
`get-skill-details`	Get full details of a skill
`install-skill`	Add a skill to your library
`uninstall-skill`	Remove a skill from your library
`search-marketplace`	Search the skill marketplace by name, category, or capability

Executions

Tool	Description
`get-execution-status`	Check current/recent execution status
`cancel-execution`	Cancel an active execution
`list-executions`	List recent skill executions

Artifacts

Tool	Description
`list-artifacts`	List your generated artifacts
`get-artifact`	Get details of a specific artifact
`download-artifact`	Get download URL for an artifact
`save-artifact`	Save content as a new artifact
`delete-artifact`	Remove an artifact

Billing

Tool	Description
`get-credit-balance`	Check your credit balance

Connectors

The unified connector surface — sources (code repos, files) and actions (SaaS operations) all live here. The previously-separate “Integrations” tool family was consolidated into the connector family.

Tool	Description
`list-connectors`	List available connectors and their connection status
`list-github-repos`	List GitHub repositories you have access to
`list-sources`	List sources for a connector (e.g., GitHub repos)
`list-branches`	List branches for a source
`get-source-content`	Get file/directory contents from a source
`get-connector-status`	Check if a connector is authenticated
`connect-connector`	Get OAuth URL to connect a connector
`disconnect-connector`	Disconnect and revoke access
`search-connector-actions`	Search available actions for connected connectors
`run-connector-action`	Execute an action from a connected connector
`list-connector-triggers`	List event triggers a workflow can subscribe to

Workflows

Tool	Description
`start-workflow`	Start a workflow execution by ID

Install & Resources

Tool	Description
`install-resource`	Install an agent, workflow, skill, or whole template workspace into the current workspace (from a GitHub repo, an uploaded R2 object, or the marketplace)
`request-upload-url`	Mint a short-lived presigned URL for uploading bundle bytes directly to storage; pair with `install-resource` to finalize

Threads

Tool	Description
`thread-members`	List clients currently active in a thread inside this workspace (presence snapshot)

Response Format

All tools return a standardized response:

Success Response

{
  "success": true,
  "data": { ... },
  "pagination": {
    "cursor": "...",
    "hasMore": true
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Rate Limiting

MCP requests are rate-limited to 60 requests per minute per user.

Rate limit info is returned in HTTP response headers.

Pagination

List operations support cursor-based pagination:

{
  "tool": "list-installed-skills",
  "arguments": {
    "limit": 20,
    "cursor": "previous_cursor_value"
  }
}

Response includes pagination metadata at the top level:

{
  "success": true,
  "data": [...],
  "pagination": {
    "cursor": "next_cursor_value",
    "hasMore": true
  }
}

Note: Some tools (such as list-executions) use offset-based pagination instead of cursor-based. These tools accept an offset parameter rather than a cursor.

Client Configuration

See MCP Client Setup for detailed setup instructions for:

Claude Desktop
Cursor
VS Code
Custom clients

Error Codes

Code	Description
`NOT_FOUND`	Resource doesn’t exist
`ALREADY_EXISTS`	Resource already exists
`INSUFFICIENT_CREDITS`	Not enough credits
`EXECUTION_RUNNING`	Another execution is active
`EXECUTION_FAILED`	Skill execution failed
`RATE_LIMITED`	Too many requests
`UNAUTHORIZED`	Invalid or missing auth, or connector not connected
`LIMIT_REACHED`	Tier limit exceeded
`INVALID_INPUT`	Invalid connector type or connector not configured
`CONNECTOR_ERROR`	Connector-specific operational error
`GITHUB_ERROR`	GitHub API error
`TIMEOUT`	Request exceeded timeout limit

Best Practices

Check status first - Before executing, verify no execution is running
Handle pagination - Always check hasMore and use cursors
Respect rate limits - Check x-ratelimit-remaining in response headers
Handle timeouts gracefully - Long-running operations may timeout