API Reference

Complete reference for MA²D’s MCP-compliant API endpoints with multi-language SDK examples.

Overview

MA²D exposes MCP (Model Context Protocol) endpoints that allow AI agents to interact with your designed servers. All endpoints follow the JSON-RPC 2.0 specification and can be accessed using cURL or official SDKs.

Base URL Structure

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

Available SDKs:

cURL (command line)
TypeScript / JavaScript
Python
Go
Kotlin / Java
C# / .NET
Ruby
Rust
PHP
Swift

Parameters:

{serverId}: UUID of the MCP server

Example:

https://ma2d.vercel.app/api/platform/550e8400-e29b-41d4-a716-446655440000/mcp

Protocol Specification

MA²D implements MCP protocol version 2024-11-05 with HTTP-Streamable transport:

Protocol: JSON-RPC 2.0
Transport: HTTP with Server-Sent Events (SSE)
Content-Type: application/json
Response: text/event-stream

Quick Start

1. Get Your Server ID

From the MA²D dashboard:

Navigate to MCP Servers
Click on a server
Copy the Server ID from the URL or settings

2. Test Your Endpoint

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

Supported Methods

Method	Description	Auth Required
`initialize`	Negotiate capabilities	No
`tools/list`	List available tools	No
`tools/call`	Execute a tool	No
`resources/list`	List available resources	No
`resources/read`	Read resource content	No
`prompts/list`	List available prompts	No
`prompts/get`	Get prompt template	No

Note: MCP endpoints are public by design. Authentication is optional and can be configured per server.

Request Format

All requests must follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "method_name",
  "params": {
    // Method-specific parameters
  }
}

Required Fields:

jsonrpc: Must be "2.0"
id: Request identifier (number or string)
method: MCP method name

Optional Fields:

params: Method parameters (object)

Response Format

Success Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    // Method-specific result
  }
}

Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      // Additional error details
    }
  }
}

Standard Error Codes

Code	Name	Description
`-32700`	Parse error	Invalid JSON
`-32600`	Invalid request	Malformed request
`-32601`	Method not found	Unknown method
`-32602`	Invalid params	Bad parameters
`-32603`	Internal error	Server error
`-32001`	Unauthorized	Authentication failed

Server-Sent Events (SSE)

MCP uses SSE for streaming responses:

POST /api/platform/{serverId}/mcp HTTP/1.1
Content-Type: application/json
 
{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Response:

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

Benefits:

Real-time streaming
Long-lived connections
Progress updates for long operations

Rate Limits

MA²D does not currently enforce rate limits on MCP endpoints, but we recommend:

Development: Up to 100 requests/minute
Production: Up to 1,000 requests/minute

Excessive usage may be throttled to protect service availability.

CORS Policy

MCP endpoints support CORS for browser-based clients:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Preflight Requests: Supported via OPTIONS method

Best Practices

1. Reuse Server Instances

Don’t create a new connection for every request. MA²D is stateless, so you can:

const endpoint = `https://ma2d.vercel.app/api/platform/${serverId}/mcp`
 
// Make multiple requests to same endpoint
await callTool(endpoint, "get_weather", { city: "SF" })
await callTool(endpoint, "get_weather", { city: "NYC" })

2. Handle Errors Gracefully

Always check for error responses:

const response = await fetch(endpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(request)
})
 
const data = await response.json()
 
if (data.error) {
  console.error('MCP Error:', data.error.message)
  // Handle error
} else {
  // Process result
  console.log(data.result)
}

3. Validate Input

Validate tool arguments against the tool’s input schema:

import Ajv from 'ajv'
 
const ajv = new Ajv()
const validate = ajv.compile(tool.inputSchema)
 
if (!validate(arguments)) {
  throw new Error(`Invalid arguments: ${ajv.errorsText(validate.errors)}`)
}

4. Use TypeScript

Type-safe MCP client:

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/${serverId}/mcp`
})
 
const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: {}
})
 
await client.connect(transport)
const tools = await client.listTools()

5. Monitor Performance

Track response times:

const start = Date.now()
const response = await callMCPEndpoint(...)
const duration = Date.now() - start
 
console.log(`Request completed in ${duration}ms`)

Example: Complete Workflow

// 1. Initialize connection
const initRequest = {
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    clientInfo: {
      name: "my-agent",
      version: "1.0.0"
    },
    capabilities: {}
  }
}
 
// 2. List available tools
const listRequest = {
  jsonrpc: "2.0",
  id: 2,
  method: "tools/list"
}
 
// 3. Call a tool
const callRequest = {
  jsonrpc: "2.0",
  id: 3,
  method: "tools/call",
  params: {
    name: "get_weather",
    arguments: {
      city: "San Francisco"
    }
  }
}

Testing Tools

cURL

curl -X POST $ENDPOINT \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Postman

Create POST request
Set URL to MCP endpoint
Headers: Content-Type: application/json
Body: Raw JSON with request

MCP Inspector

Official MCP testing tool:

npx @modelcontextprotocol/inspector \
  https://ma2d.vercel.app/api/platform/YOUR_SERVER_ID/mcp

Custom Client

Use the official SDK:

npm install @modelcontextprotocol/sdk

API Status

Check API status:

Health: https://ma2d.vercel.app/api/health
Uptime: 99.9% SLA (Vercel infrastructure)

Next Steps

Explore detailed endpoint documentation with multi-language examples:

MCP Endpoints - Complete method reference with cURL, TypeScript, Python, Go, Java, and more

Support

Documentation: Browse this documentation for detailed guides
GitHub Issues: Report bugs
MCP Specification: Official MCP Docs

API Version: 2024-11-05
Last Updated: January 2026
Stability: Stable

Consuming MCP via REST API MCP Endpoints