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 (POST /mcp) supports the following methods:

Method	Purpose	Session Required
`initialize`	Start new MCP session	No
`tools/list`	List available tools	Yes
`tools/call`	Execute a tool	Yes

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

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

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.

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
}

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

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
  }'

Future Methods

The following MCP methods are planned but not yet implemented:

resources/list - List available resources
resources/read - Read resource content
prompts/list - List available prompts
prompts/get - Get prompt template
sampling/createMessage - Request LLM completion

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

MCP Endpoints ​

Overview ​

JSON-RPC 2.0 Format ​

initialize ​

Request ​

Parameters ​

Response ​

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 ​

Best Practices ​

Client Implementation ​

Tool Development ​

Testing Tools ​

Test seed_ping ​

Future Methods ​

Related Documentation ​

MCP Endpoints

Overview

JSON-RPC 2.0 Format

initialize

Request

Parameters

Response

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

Best Practices

Client Implementation

Tool Development

Testing Tools

Test seed_ping

Future Methods

Related Documentation