MCP Endpoints

Complete reference for all MCP protocol endpoints with multi-language SDK examples.

Endpoint URL

POST https://your-domain.com/api/platform/{serverId}/mcp

All MCP methods use the same POST endpoint with different method values in the request body.

Available SDKs

The Model Context Protocol provides official SDKs for multiple languages:

Language	Package	Repository
cURL	Built-in	Command line
TypeScript	`@modelcontextprotocol/sdk`	GitHub
Python	`mcp`	GitHub
Go	`go-sdk`	GitHub
Kotlin	`kotlin-sdk`	GitHub
Java	`java-sdk`	GitHub
C#	`csharp-sdk`	GitHub
Ruby	`ruby-sdk`	GitHub
Rust	`rust-sdk`	GitHub
PHP	`php-sdk`	GitHub
Swift	`swift-sdk`	GitHub

All examples below show how to call each endpoint using different languages and SDKs.

Initialize

Negotiate capabilities and protocol version with the server.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    },
    "capabilities": {}
  }
}

Parameters:

Field	Type	Required	Description
`protocolVersion`	string	Yes	MCP protocol version (e.g., “2024-11-05”)
`clientInfo`	object	Yes	Client identification
`clientInfo.name`	string	Yes	Client name
`clientInfo.version`	string	Yes	Client version
`capabilities`	object	Yes	Client capabilities (can be empty)

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "My MCP Server",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    }
  }
}

Result Fields:

Field	Type	Description
`protocolVersion`	string	Protocol version server supports
`serverInfo`	object	Server identification
`serverInfo.name`	string	Server name (from MA²D config)
`serverInfo.version`	string	Server version (from MA²D config)
`capabilities`	object	What the server supports
`capabilities.tools`	object	Server provides tools (if any exist)
`capabilities.resources`	object	Server provides resources (if any exist)
`capabilities.prompts`	object	Server provides prompts (if any exist)

Examples

curl -X POST https://ma2d.vercel.app/api/platform/abc123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      },
      "capabilities": {}
    }
  }'

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamable-http.js'
 
const transport = new StreamableHTTPClientTransport({
  url: 'https://ma2d.vercel.app/api/platform/abc123/mcp'
})
 
const client = new Client({
  name: 'test-client',
  version: '1.0.0'
}, {
  capabilities: {}
})
 
await client.connect(transport)

from mcp import Client
from mcp.client.streamable_http import StreamableHTTPClientTransport
 
transport = StreamableHTTPClientTransport(
    url='https://ma2d.vercel.app/api/platform/abc123/mcp'
)
 
client = Client(
    name='test-client',
    version='1.0.0'
)
 
await client.connect(transport)

import (
    "context"
    "github.com/modelcontextprotocol/go-sdk/client"
    "github.com/modelcontextprotocol/go-sdk/transport"
)
 
transport := transport.NewStreamableHTTPTransport(
    "https://ma2d.vercel.app/api/platform/abc123/mcp",
)
 
client := client.NewClient(client.Config{
    Name:    "test-client",
    Version: "1.0.0",
})
 
ctx := context.Background()
err := client.Connect(ctx, transport)

import io.mcp.client.Client;
import io.mcp.client.StreamableHTTPTransport;
 
StreamableHTTPTransport transport = new StreamableHTTPTransport(
    "https://ma2d.vercel.app/api/platform/abc123/mcp"
);
 
Client client = new Client.Builder()
    .name("test-client")
    .version("1.0.0")
    .build();
 
client.connect(transport);

Tools/List

List all available tools provided by the server.

Request

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

Parameters: None required.

You can optionally include a params object with cursor for pagination (not currently implemented in MA²D).

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }
}

Result Fields:

Field	Type	Description
`tools`	array	List of available tools
`tools[].name`	string	Tool identifier (unique)
`tools[].description`	string	What the tool does
`tools[].inputSchema`	object	JSON Schema for tool input

Input Schema: Standard JSON Schema (Draft 7) defining:

Parameter names and types
Descriptions for each parameter
Required vs optional parameters
Validation rules (min, max, pattern, etc.)

Examples

curl -X POST https://ma2d.vercel.app/api/platform/abc123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

const tools = await client.listTools()
console.log('Available tools:', tools)

tools = await client.list_tools()
print('Available tools:', tools)

tools, err := client.ListTools(ctx)
if err != nil {
    panic(err)
}
fmt.Printf("Available tools: %+v\n", tools)

List<Tool> tools = client.listTools();
System.out.println("Available tools: " + tools);

Tools/Call

Execute a tool with the provided arguments.

Request

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "San Francisco"
    }
  }
}

Parameters:

Field	Type	Required	Description
`name`	string	Yes	Tool name from tools/list
`arguments`	object	No	Tool-specific arguments (must match inputSchema)

Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"temperature\": 72, \"conditions\": \"Sunny\"}"
      }
    ]
  }
}

Result Fields:

Field	Type	Description
`content`	array	Array of content items
`content[].type`	string	Content type (“text”, “image”, “resource”)
`content[].text`	string	Text content (for type=“text”)

Content Types:

MA²D currently supports text type. The text typically contains JSON-encoded data.

Error Response

If arguments are invalid:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params: missing required field 'city'"
  }
}

If tool not found:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32601,
    "message": "Tool not found: get_weather"
  }
}

Mock Execution

MA²D executes mock scenarios based on condition matching:

Scenario Example:

{
  "condition": {
    "field": "city",
    "operator": "equals",
    "value": "San Francisco"
  },
  "response": {
    "temperature": 72,
    "conditions": "Sunny"
  }
}

Matching Logic:

Find scenarios for the tool
Evaluate conditions against arguments
Return first matching scenario’s response
If no match, return default response

Learn more about mock scenarios →

Examples

curl -X POST https://ma2d.vercel.app/api/platform/abc123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": {
        "city": "San Francisco"
      }
    }
  }'

const result = await client.callTool({
  name: 'get_weather',
  arguments: {
    city: 'San Francisco'
  }
})
console.log('Result:', result)

result = await client.call_tool(
    name='get_weather',
    arguments={'city': 'San Francisco'}
)
print('Result:', result)

result, err := client.CallTool(ctx, "get_weather", map[string]interface{}{
    "city": "San Francisco",
})
if err != nil {
    panic(err)
}
fmt.Printf("Result: %+v\n", result)

Map<String, Object> arguments = new HashMap<>();
arguments.put("city", "San Francisco");
 
ToolResult result = client.callTool("get_weather", arguments);
System.out.println("Result: " + result);

Resources/List

List all available resources provided by the server.

Request

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

Parameters: None required.

Response

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resources": [
      {
        "uri": "weather://cities",
        "name": "Available Cities",
        "description": "List of cities with weather data",
        "mimeType": "application/json"
      }
    ]
  }
}

Result Fields:

Field	Type	Description
`resources`	array	List of available resources
`resources[].uri`	string	Unique resource identifier
`resources[].name`	string	Human-readable name
`resources[].description`	string	What the resource contains
`resources[].mimeType`	string	Content type (optional)

Resource URIs: Follow custom scheme format:

weather://cities
docs://api/v1
data://users/{userId}

Examples

curl -X POST https://ma2d.vercel.app/api/platform/abc123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "resources/list"
  }'

const resources = await client.listResources()
console.log('Available resources:', resources)

resources = await client.list_resources()
print('Available resources:', resources)

resources, err := client.ListResources(ctx)
if err != nil {
    panic(err)
}
fmt.Printf("Available resources: %+v\n", resources)

List<Resource> resources = client.listResources();
System.out.println("Available resources: " + resources);

Resources/Read

Read the content of a specific resource.

Request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/read",
  "params": {
    "uri": "weather://cities"
  }
}

Parameters:

Field	Type	Required	Description
`uri`	string	Yes	Resource URI from resources/list

Response

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "contents": [
      {
        "uri": "weather://cities",
        "mimeType": "application/json",
        "text": "[\"San Francisco\", \"New York\", \"London\"]"
      }
    ]
  }
}

Result Fields:

Field	Type	Description
`contents`	array	Array of content items
`contents[].uri`	string	Resource URI
`contents[].mimeType`	string	Content type
`contents[].text`	string	Resource content (text/JSON)

Examples

curl -X POST https://ma2d.vercel.app/api/platform/abc123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "resources/read",
    "params": {
      "uri": "weather://cities"
    }
  }'

const content = await client.readResource({
  uri: 'weather://cities'
})
console.log('Resource content:', content)

content = await client.read_resource(uri='weather://cities')
print('Resource content:', content)

content, err := client.ReadResource(ctx, "weather://cities")
if err != nil {
    panic(err)
}
fmt.Printf("Resource content: %+v\n", content)

ResourceContent content = client.readResource("weather://cities");
System.out.println("Resource content: " + content);

Prompts/List

List all available prompt templates.

Request

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

Parameters: None required.

Response

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "prompts": [
      {
        "name": "weather_query",
        "description": "Template for weather queries",
        "arguments": [
          {
            "name": "location",
            "description": "Location to query",
            "required": true
          }
        ]
      }
    ]
  }
}

Result Fields:

Field	Type	Description
`prompts`	array	List of available prompts
`prompts[].name`	string	Prompt identifier
`prompts[].description`	string	What the prompt does
`prompts[].arguments`	array	Prompt arguments
`arguments[].name`	string	Argument name
`arguments[].description`	string	What the argument is for
`arguments[].required`	boolean	Whether required

Examples

curl -X POST https://ma2d.vercel.app/api/platform/abc123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "prompts/list"
  }'

const prompts = await client.listPrompts()
console.log('Available prompts:', prompts)

prompts = await client.list_prompts()
print('Available prompts:', prompts)

prompts, err := client.ListPrompts(ctx)
if err != nil {
    panic(err)
}
fmt.Printf("Available prompts: %+v\n", prompts)

List<Prompt> prompts = client.listPrompts();
System.out.println("Available prompts: " + prompts);

Prompts/Get

Get a prompt template with arguments filled in.

Request

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "prompts/get",
  "params": {
    "name": "weather_query",
    "arguments": {
      "location": "San Francisco"
    }
  }
}

Parameters:

Field	Type	Required	Description
`name`	string	Yes	Prompt name from prompts/list
`arguments`	object	No	Argument values

Response

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What's the weather in San Francisco?"
        }
      }
    ]
  }
}

Result Fields:

Field	Type	Description
`messages`	array	Array of messages
`messages[].role`	string	Message role (“user”, “assistant”)
`messages[].content`	object	Message content
`content.type`	string	Content type (“text”)
`content.text`	string	Message text

Examples

curl -X POST https://ma2d.vercel.app/api/platform/abc123/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "prompts/get",
    "params": {
      "name": "weather_query",
      "arguments": {
        "location": "San Francisco"
      }
    }
  }'

const prompt = await client.getPrompt({
  name: 'weather_query',
  arguments: {
    location: 'San Francisco'
  }
})
console.log('Prompt:', prompt)

prompt = await client.get_prompt(
    name='weather_query',
    arguments={'location': 'San Francisco'}
)
print('Prompt:', prompt)

prompt, err := client.GetPrompt(ctx, "weather_query", map[string]interface{}{
    "location": "San Francisco",
})
if err != nil {
    panic(err)
}
fmt.Printf("Prompt: %+v\n", prompt)

Map<String, Object> arguments = new HashMap<>();
arguments.put("location", "San Francisco");
 
PromptResult prompt = client.getPrompt("weather_query", arguments);
System.out.println("Prompt: " + prompt);

Response Streaming

MA²D uses Server-Sent Events (SSE) for responses:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
 
data: {"jsonrpc":"2.0","id":1,"result":{...}}

Parsing SSE:

const response = await fetch(endpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request)
})
 
const reader = response.body.getReader()
const decoder = new TextDecoder()
 
let buffer = ''
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  
  buffer += decoder.decode(value, { stream: true })
  
  const lines = buffer.split('\n')
  buffer = lines.pop() // Keep incomplete line
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6))
      console.log('Received:', data)
    }
  }
}

Next Steps

MCP Methods Reference - Complete method reference
Consuming MCP via REST API - More language examples
Creating Your First MCP Server - Build a server

Protocol Version: 2024-11-05
Reference: MCP Specification

Overview Overview