Docs/API Reference

API Reference

RESTful API and MCP SSE transport. All requests authenticated via API key. Base URL: https://claritycoremcp-live.up.railway.app

Authentication

All API requests require authentication via the X-API-Key header. API keys are prefixed with cc_live_ for production and cc_test_ for sandbox environments.

Authentication

# API Key authentication (recommended for programmatic access)
curl -H "X-API-Key: cc_live_YOUR_KEY_HERE" \
  https://claritycoremcp-live.up.railway.app/mcp/tools

Endpoints

Method	Path	Description	Tier
GET	`/mcp/tools`	List all available MCP tools with schemas	All
POST	`/mcp/execute`	Execute a tool by name with arguments	All
GET	`/mcp/tools/:name`	Get a single tool's schema and metadata	All
GET	`/sse`	Server-Sent Events stream for MCP protocol	All
POST	`/auth/login`	Authenticate and receive session token	All
GET	`/users/me`	Get current user profile and plan details	All
GET	`/usage`	Get usage statistics for the current billing period	All
POST	`/api-keys`	Generate a new API key	All
DELETE	`/api-keys/:id`	Revoke an API key	All
GET	`/admin/businesses`	List all tenant businesses (admin only)	Enterprise
GET	`/admin/analytics`	Platform-wide analytics and KPIs	Enterprise

Execute a Tool

The primary endpoint. Send a tool name and arguments, receive structured results with source citations.

POST /mcp/execute

curl -X POST https://claritycoremcp-live.up.railway.app/mcp/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cc_live_YOUR_KEY_HERE" \
  -d '{
    "tool": "deep_research",
    "arguments": {
      "query": "Medicare Advantage prior authorization requirements 2026",
      "depth": "comprehensive"
    }
  }'

Response

200 OK

{
  "status": "success",
  "result": {
    "content": "...",
    "sources": [
      {
        "title": "CMS Final Rule CMS-4201-F",
        "url": "https://www.cms.gov/...",
        "confidence": 0.97
      }
    ],
    "verification_score": 0.94
  },
  "usage": {
    "tokens_used": 2847,
    "tools_called": 3,
    "latency_ms": 1243
  }
}

SSE Transport (MCP Protocol)

For MCP clients like Claude Desktop and Cursor, connect via the SSE endpoint. The server implements the full MCP protocol over Server-Sent Events.

SSE Connection

# Connect via SSE for MCP protocol
curl -N -H "X-API-Key: cc_live_YOUR_KEY_HERE" \
  https://claritycoremcp-live.up.railway.app/sse

# The server sends MCP protocol messages as SSE events:
# event: message
# data: {"jsonrpc":"2.0","method":"tools/list","result":{...}}

Rate Limits

Rate limits are applied per API key. Headers X-RateLimit-Remaining and Retry-After are included in every response.

Plan	Requests	Tool Calls	Concurrent
Starter	100 / minute	1,000 / day	5
Professional	500 / minute	10,000 / day	25
Private	2,000 / minute	Unlimited	100
Enterprise	Custom	Unlimited	Custom

Error Codes

Error Response Format

{
  "status": "error",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 2 seconds.",
    "retry_after": 2
  }
}

Code	Name	Description
`400`	Bad Request	Invalid request body or missing required parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks permission for this resource or tool tier
`404`	Not Found	Endpoint or tool does not exist
`429`	Rate Limited	Too many requests. Check Retry-After header
`500`	Internal Error	Server error. Contact support if persistent
`503`	Service Unavailable	Temporary maintenance. Retry with exponential backoff