MCP Endpoints

This page provides detailed reference for MCP (Model Context Protocol) methods supported by Seed. All MCP communication happens through the /mcp endpoint via JSON-RPC 2.0.

Overview

The MCP endpoint supports the following methods:

Method	HTTP Method	Purpose	Session Required
`initialize`	POST	Start new MCP session	No
`tools/list`	POST	List available tools	Yes
`tools/call`	POST	Execute a tool	Yes
`prompts/list`	POST	List available prompts	Yes
`prompts/get`	POST	Get prompt template	Yes
`resources/list`	POST	List available resources	Yes
`resources/read`	POST	Read resource content	Yes
Session termination	DELETE	Terminate MCP session	Yes

MCP Request Flow

JSON-RPC 2.0 Format

All MCP requests and responses follow JSON-RPC 2.0 specification:

Request Format:

json

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": { /* method parameters */ },
  "id": 1
}

Response Format (Success):

json

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

Response Format (Error):

json

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Error description"
  },
  "id": 1
}

initialize

Start a new MCP session - Establishes protocol version and exchanges capabilities.

Request

http

POST /mcp
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "0.1.0",
    "capabilities": {},
    "clientInfo": {
      "name": "Claude Desktop",
      "version": "1.0.0"
    }
  },
  "id": 1
}

Parameters

Field	Type	Required	Description
`protocolVersion`	string	Yes	MCP protocol version (e.g., "0.1.0")
`capabilities`	object	Yes	Client capabilities (empty object for now)
`clientInfo`	object	No	Client metadata
`clientInfo.name`	string	No	Client name
`clientInfo.version`	string	No	Client version

Response

http

HTTP/1.1 200 OK
Content-Type: application/json
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000
X-Session-Expires-At: 2026-01-08T14:30:00.000Z

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "0.1.0",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "seed",
      "version": "0.1.3"
    }
  },
  "id": 1
}

Response Headers

Header	Description
`mcp-session-id`	Unique session identifier (UUID). Include in all subsequent requests.
`X-Session-Expires-At`	ISO 8601 timestamp indicating when the session will expire (24 hours from request).

Response Fields

Field	Type	Description
`protocolVersion`	string	MCP protocol version supported by server
`capabilities`	object	Server capabilities
`capabilities.tools`	object	Tool support enabled (empty object)
`serverInfo`	object	Server metadata
`serverInfo.name`	string	Server name from package.json
`serverInfo.version`	string	Server version from package.json

Important:

The response includes mcp-session-id header. Clients must include this header in all subsequent requests.
The X-Session-Expires-At header indicates session expiration time. Clients can use this to warn users or proactively refresh sessions.

Example

javascript

const response = await fetch('https://seed.example.com/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '0.1.0',
      capabilities: {},
      clientInfo: {
        name: 'My MCP Client',
        version: '1.0.0',
      },
    },
    id: 1,
  }),
});

const sessionId = response.headers.get('mcp-session-id');
const data = await response.json();

tools/list

List available MCP tools - Retrieves all tools registered on the server with their schemas.

Request

http

POST /mcp
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 2
}

Parameters

No parameters required (empty object).

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "seed_ping",
        "description": "Ping the Seed server to test connectivity",
        "inputSchema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "Optional message to include in the response"
            }
          },
          "additionalProperties": false
        }
      }
    ]
  },
  "id": 2
}

Response Fields

Field	Type	Description
`tools`	array	Array of available tools
`tools[].name`	string	Tool identifier (used in tools/call)
`tools[].description`	string	Human-readable tool description
`tools[].inputSchema`	object	JSON Schema for tool parameters

Input Schema

Each tool's inputSchema follows JSON Schema Draft 7:

json

{
  "type": "object",
  "properties": {
    "param_name": {
      "type": "string|number|boolean|object|array",
      "description": "Parameter description",
      "optional": true
    }
  },
  "required": ["required_param"],
  "additionalProperties": false
}

Example

javascript

const response = await fetch('https://seed.example.com/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'mcp-session-id': sessionId,
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/list',
    params: {},
    id: 2,
  }),
});

const { result } = await response.json();
console.log('Available tools:', result.tools.map(t => t.name));

tools/call

Execute an MCP tool - Calls a tool with provided arguments and returns the result.

Request

http

POST /mcp
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "seed_ping",
    "arguments": {
      "message": "Hello from Claude"
    }
  },
  "id": 3
}

Parameters

Field	Type	Required	Description
`name`	string	Yes	Tool name (from tools/list)
`arguments`	object	Yes	Tool parameters matching inputSchema

Response (Success)

json

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Seed MCP Server: Hello from Claude"
      }
    ]
  },
  "id": 3
}

Response (Tool Error)

json

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: Invalid message parameter"
      }
    ],
    "isError": true
  },
  "id": 3
}

Response Fields

Field	Type	Description
`content`	array	Array of content items
`content[].type`	string	Content type: `text`, `image`, or `resource`
`content[].text`	string	Text content (if type is `text`)
`content[].data`	string	Base64 image data (if type is `image`)
`content[].mimeType`	string	MIME type (if type is `image`)
`isError`	boolean	True if tool execution failed (optional)

Content Types

Text Content

json

{
  "type": "text",
  "text": "Plain text or markdown content"
}

Image Content

json

{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/png"
}

Resource Content

json

{
  "type": "resource",
  "resource": {
    "uri": "https://example.com/resource",
    "name": "Resource Name",
    "description": "Resource description"
  }
}

Example

javascript

// Call tool
const response = await fetch('https://seed.example.com/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'mcp-session-id': sessionId,
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: {
      name: 'seed_ping',
      arguments: {
        message: 'test',
      },
    },
    id: 3,
  }),
});

const { result } = await response.json();

// Check for errors
if (result.isError) {
  console.error('Tool error:', result.content[0].text);
} else {
  console.log('Tool result:', result.content[0].text);
}

Available Tools

seed_ping

Test connectivity - Ping the Seed server to verify it's responding.

Parameters:

typescript

{
  message?: string;  // Optional message to echo
}

Example:

json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "seed_ping",
    "arguments": {
      "message": "hello"
    }
  },
  "id": 1
}

Response:

json

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Seed MCP Server: hello"
      }
    ]
  },
  "id": 1
}

Error Handling

Protocol Errors

Invalid Request - Malformed JSON-RPC request.

json

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "details": "Missing required field: method"
    }
  },
  "id": null
}

JSON-RPC Error Codes

Code	Name	Description
-32700	Parse error	Invalid JSON
-32600	Invalid Request	Missing required fields
-32601	Method not found	Unknown method
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Server error

Tool Errors

Tools can return errors in two ways:

1. Using isError flag:

json

{
  "content": [{"type": "text", "text": "Error message"}],
  "isError": true
}

2. Throwing exception (results in JSON-RPC error):

json

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Tool execution failed",
    "data": {
      "details": "Exception message"
    }
  },
  "id": 3
}

DELETE /mcp

Terminate an MCP session - Explicitly ends a session and cleans up server resources.

Request

http

DELETE /mcp
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000

Parameters

No body parameters required. Session ID must be provided in the mcp-session-id header.

Response (Success)

http

HTTP/1.1 204 No Content

Response (Session Not Found)

http

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Session not found",
    "data": {
      "reason": "session_not_found",
      "details": "No active session with the provided ID"
    }
  },
  "id": null
}

Response (Missing Session ID)

http

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Bad Request",
    "data": {
      "reason": "missing_session_id",
      "details": "mcp-session-id header is required"
    }
  },
  "id": null
}

Example

javascript

// Terminate session
const response = await fetch('https://seed.example.com/mcp', {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'mcp-session-id': sessionId,
  },
});

if (response.status === 204) {
  console.log('Session terminated successfully');
} else if (response.status === 404) {
  console.log('Session not found or already expired');
}

When to Use

Graceful shutdown: Client is closing and wants to clean up
Session reset: Client wants to start fresh with new initialize
Resource cleanup: Explicitly free server resources before TTL expiration

Note: Sessions also expire automatically after 24 hours of inactivity (configurable). Explicit deletion is optional but recommended for proper cleanup.

Best Practices

Client Implementation

Initialize once: Create one session per connection
Store session ID: Cache for subsequent requests
List tools on startup: Cache tool schemas
Validate parameters: Check against inputSchema before calling
Handle isError flag: Check tool-level errors
Implement timeouts: Set client-side request timeouts
Retry logic: Retry on network errors, not protocol errors
Terminate gracefully: Call DELETE /mcp when closing connection
Handle 429 rate limits: Implement exponential backoff and respect retry-after

Tool Development

When creating new tools (see Adding MCP Tools):

Use descriptive names: Tool name should be clear (e.g., get_user_info)
Write clear descriptions: Help clients understand tool purpose
Define schema precisely: Use JSON Schema for parameter validation
Return structured content: Use appropriate content types
Handle errors gracefully: Return isError for expected failures
Throw for unexpected errors: Let SDK handle unexpected exceptions
Test thoroughly: Write unit tests for all tools

Testing Tools

Test seed_ping

bash

# Initialize session
SESSION_ID=$(curl -s -X POST https://seed.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{}},"id":1}' \
  | grep -o 'mcp-session-id: [^"]*' | cut -d' ' -f2)

# Call ping tool
curl -X POST https://seed.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "seed_ping",
      "arguments": {"message": "test"}
    },
    "id": 2
  }'

prompts/list

List available prompts - Retrieves all prompt templates registered on the server.

Request

http

POST /mcp
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000

{
  "jsonrpc": "2.0",
  "method": "prompts/list",
  "params": {},
  "id": 4
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "prompts": [
      {
        "name": "greeting",
        "description": "Generate a personalized greeting message",
        "arguments": [
          {
            "name": "name",
            "description": "Name of the person to greet",
            "required": true
          },
          {
            "name": "style",
            "description": "Greeting style: formal, casual, or friendly",
            "required": false
          }
        ]
      },
      {
        "name": "user-context",
        "description": "Generate context-aware messages using user profile",
        "arguments": [
          {
            "name": "messageType",
            "description": "Type of message: welcome, status, or summary",
            "required": false
          }
        ]
      }
    ]
  },
  "id": 4
}

Available Prompts:

greeting - Personalized greetings (no auth required)
user-context - User-aware messages (auth required)

For detailed prompt documentation, see MCP Prompts.

prompts/get

Get prompt template - Retrieves a specific prompt with filled parameters.

Request

http

POST /mcp
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000

{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "params": {
    "name": "greeting",
    "arguments": {
      "name": "Alice",
      "style": "friendly"
    }
  },
  "id": 5
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Hello Alice! 👋 It's great to see you!"
        }
      }
    ]
  },
  "id": 5
}

resources/list

List available resources - Retrieves all resources exposed by the server.

Request

http

POST /mcp
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000

{
  "jsonrpc": "2.0",
  "method": "resources/list",
  "params": {},
  "id": 6
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "resources": [
      {
        "uri": "config://server",
        "name": "Server Configuration",
        "description": "Server configuration and feature flags",
        "mimeType": "application/json"
      },
      {
        "uri": "user://profile",
        "name": "User Profile",
        "description": "Authenticated user profile from JWT token",
        "mimeType": "application/json"
      }
    ]
  },
  "id": 6
}

Available Resources:

config://server - Server configuration (no auth required)
user://profile - User profile data (auth required)

For detailed resource documentation, see MCP Resources.

resources/read

Read resource content - Retrieves the content of a specific resource by URI.

Request

http

POST /mcp
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
mcp-session-id: 123e4567-e89b-12d3-a456-426614174000

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": {
    "uri": "user://profile"
  },
  "id": 7
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "contents": [
      {
        "uri": "user://profile",
        "mimeType": "application/json",
        "text": "{\"sub\":\"user123\",\"email\":\"alice@example.com\",\"name\":\"Alice\",\"groups\":[\"users\"]}"
      }
    ]
  },
  "id": 7
}

Future Methods

The following MCP methods are planned but not yet implemented:

sampling/createMessage - Request LLM completion from server

Authentication Endpoints - MCP endpoint authentication
MCP Server Design - Implementation details
Adding MCP Tools - Creating custom tools

MCP Endpoints ​

Overview ​

MCP Request Flow ​

JSON-RPC 2.0 Format ​

initialize ​

Request ​

Parameters ​

Response ​

Response Headers ​

Response Fields ​

Example ​

tools/list ​

Request ​

Parameters ​

Response ​

Response Fields ​

Input Schema ​

Example ​

tools/call ​

Request ​

Parameters ​

Response (Success) ​

Response (Tool Error) ​

Response Fields ​

Content Types ​

Text Content ​

Image Content ​

Resource Content ​

Example ​

Available Tools ​

seed_ping ​

Error Handling ​

Protocol Errors ​

JSON-RPC Error Codes ​

Tool Errors ​

DELETE /mcp ​

Request ​

Parameters ​

Response (Success) ​

Response (Session Not Found) ​

Response (Missing Session ID) ​

Example ​

When to Use ​

Best Practices ​

Client Implementation ​

Tool Development ​

Testing Tools ​

Test seed_ping ​

prompts/list ​

Request ​

Response ​

prompts/get ​

Request ​

Response ​

resources/list ​

Request ​

Response ​

resources/read ​

Request ​

Response ​

Future Methods ​

Related Documentation ​

MCP Endpoints

Overview

MCP Request Flow

JSON-RPC 2.0 Format

initialize

Request

Parameters

Response

Response Headers

Response Fields

Example

tools/list

Request

Parameters

Response

Response Fields

Input Schema

Example

tools/call

Request

Parameters

Response (Success)

Response (Tool Error)

Response Fields

Content Types

Text Content

Image Content

Resource Content

Example

Available Tools

seed_ping

Error Handling

Protocol Errors

JSON-RPC Error Codes

Tool Errors

DELETE /mcp

Request

Parameters

Response (Success)

Response (Session Not Found)

Response (Missing Session ID)

Example

When to Use

Best Practices

Client Implementation

Tool Development

Testing Tools

Test seed_ping

prompts/list

Request

Response

prompts/get

Request

Response

resources/list

Request

Response

resources/read

Request

Response

Future Methods

Related Documentation