API Reference

Complete reference for all Seed endpoints.

API Architecture Overview

Endpoint Categories

Authentication Endpoints

Protected MCP endpoints that require valid JWT tokens.

• POST /mcp - MCP JSON-RPC endpoint

OAuth Endpoints

OAuth 2.1 flow implementation for Claude clients.

• POST /oauth/register - Dynamic client registration
• GET /oauth/authorize - Authorization endpoint
• POST /oauth/token - Token endpoint
• POST /oauth/revoke - Token revocation

Discovery Endpoints

OAuth 2.0 discovery, health monitoring, and observability.

• GET /.well-known/oauth-authorization-server - OAuth server metadata
• GET /.well-known/oauth-protected-resource - Resource server metadata
• GET /health - Liveness probe (health check)
• GET /health/ready - Readiness probe (dependency health)
• GET /metrics - Prometheus metrics

Authentication

Most endpoints require authentication via JWT bearer tokens:

Authorization: Bearer <JWT_TOKEN>

Response Formats

JSON-RPC 2.0 (MCP Endpoints)

All MCP endpoints use JSON-RPC 2.0 format:

Success:

{
  "jsonrpc": "2.0",
  "result": { /* response data */ },
  "id": 1
}

Error:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": {
      "reason": "invalid_token",
      "details": "Additional context"
    }
  },
  "id": null
}

OAuth 2.0 (OAuth Endpoints)

OAuth endpoints use RFC 6749 error format:

{
  "error": "invalid_client",
  "error_description": "Client not found or expired"
}

For complete error handling documentation, see Error Handling Architecture.

Rate Limiting

MCP Endpoints (POST /mcp, DELETE /mcp):

• Per-IP: 100 requests/minute
• Global: 10,000 requests/minute

OAuth Registration (POST /oauth/register):

• Per-IP: 10 registrations/hour
• Global: 1,000 registrations/hour

OAuth Authorization (GET /oauth/authorize):

• Per-IP: 10 requests/minute
• Global: 1,000 requests/minute

Rate limited requests return 429 with Retry-After header and X-RateLimit-* headers.

For detailed rate limiting information, see Rate Limiting Architecture.

Explore Further

• Authentication Endpoints - MCP endpoint details
• OAuth Endpoints - OAuth flow endpoints
• MCP Endpoints - MCP tools and resources
• Health & Discovery - Metadata and health

Status Codes

Code	Meaning	When Used
200	Success	Request completed successfully
201	Created	Resource created (OAuth client registration)
204	No Content	Successful deletion (MCP session termination)
302	Found	OAuth redirect
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid JWT token
404	Not Found	Endpoint or resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error