MCP Servers API Reference

This page documents the API endpoints for managing MCP servers.

Base URL

https://api.universalapi.co

Authentication

All management endpoints require authentication via headers:

X-Uni-UserId: your-user-id
X-Uni-SecretUniversalKey: your-secret-key

Endpoints

List MCP Servers

GET /mcp-server/list

Response:

{
  "success": true,
  "data": {
    "servers": [
      {
        "serverId": "my-server-id",
        "serverName": "My Tools",
        "description": "Custom tools for my workflow",
        "visibility": "private",
        "status": "active",
        "userId": "user-id",
        "version": "1.0.0",
        "endpointUrl": "https://api.universalapi.co/mcp/my-server-id",
        "createdAt": 1736734800000,
        "updatedAt": 1736734800000
      }
    ],
    "count": 1
  }
}

Get MCP Server

GET /mcp-server/{serverId}

Response:

{
  "success": true,
  "data": {
    "serverId": "my-server-id",
    "serverName": "My Tools",
    "description": "Custom tools for my workflow",
    "visibility": "private",
    "status": "active",
    "userId": "user-id",
    "userAlias": "username",
    "version": "1.0.0",
    "runtime": "nodejs20.x",
    "memoryMb": 512,
    "timeoutSec": 60,
    "endpointUrl": "https://api.universalapi.co/mcp/my-server-id",
    "sourceCode": "const { McpServer } = require(...)...",
    "createdAt": 1736734800000,
    "updatedAt": 1736734800000
  }
}

Create MCP Server

POST /mcp-server/create

Request Body:

{
  "serverName": "My Tools",
  "description": "Custom tools for my workflow",
  "visibility": "private",
  "sourceCode": "const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');\nconst { z } = require('zod');\n\nfunction createMcpServer() {\n  const mcpServer = new McpServer({ name: 'my-tools', version: '1.0.0' });\n  mcpServer.registerTool('hello', {\n    title: 'Hello',\n    description: 'Says hello',\n    inputSchema: {}\n  }, async () => ({ content: [{ type: 'text', text: 'Hello!' }] }));\n  return mcpServer;\n}\n\nmodule.exports = { createMcpServer };",
  "memoryMb": 512,
  "timeoutSec": 60
}

Required Fields:

Field	Type	Description
serverName	string	Display name for the server
description	string	What the server does
sourceCode	string	Node.js code with createMcpServer()

Optional Fields:

Field	Type	Default	Description
visibility	string	private	public or private
memoryMb	number	512	Memory allocation (128-1024)
timeoutSec	number	60	Timeout in seconds (1-300)

Response:

{
  "success": true,
  "data": {
    "serverId": "generated-server-id",
    "serverName": "My Tools",
    "endpointUrl": "https://api.universalapi.co/mcp/generated-server-id",
    "message": "MCP server created successfully"
  }
}

Update MCP Server

PUT /mcp-server/update

Request Body:

{
  "serverId": "my-server-id",
  "serverName": "Updated Tools",
  "description": "Updated description",
  "sourceCode": "// updated code...",
  "visibility": "public"
}

Required Fields:

Field	Type	Description
serverId	string	ID of server to update

All other fields are optional and only update if provided.

Response:

{
  "success": true,
  "data": {
    "serverId": "my-server-id",
    "message": "MCP server updated successfully"
  }
}

Delete MCP Server

DELETE /mcp-server/delete

Request Body:

{
  "serverId": "my-server-id"
}

Response:

{
  "success": true,
  "data": {
    "serverId": "my-server-id",
    "message": "MCP server deleted successfully"
  }
}

MCP Protocol Endpoint

The MCP runtime endpoint handles JSON-RPC 2.0 requests:

POST /mcp/{serverId}

This endpoint does not require Universal API authentication - it handles MCP protocol messages directly.

Initialize

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

List Tools

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

Call Tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1"
    }
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "MCP_SERVER_NOT_FOUND",
    "message": "The requested MCP server does not exist",
    "timestamp": "2025-01-13T12:00:00.000Z"
  }
}

Error Codes:

Code	Description
MCP_SERVER_NOT_FOUND	Server ID doesn't exist
MCP_SERVER_EXECUTION_ERROR	Error executing server code
INVALID_SOURCE_CODE	Source code is malformed
AUTHENTICATION_REQUIRED	Missing or invalid credentials
PERMISSION_DENIED	Not authorized to access server

Example: Full Workflow

# 1. Create server
curl -X POST "https://api.universalapi.co/mcp-server/create" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY" \
  -d '{
    "serverName": "weather-tools",
    "description": "Weather lookup tools",
    "sourceCode": "..."
  }'

# 2. Test the MCP endpoint
curl -X POST "https://api.universalapi.co/mcp/weather-tools-abc123" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# 3. List your servers
curl "https://api.universalapi.co/mcp-server/list" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY"

# 4. Update server
curl -X PUT "https://api.universalapi.co/mcp-server/update" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY" \
  -d '{
    "serverId": "weather-tools-abc123",
    "description": "Updated weather tools"
  }'

# 5. Delete server
curl -X DELETE "https://api.universalapi.co/mcp-server/delete" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY" \
  -d '{"serverId": "weather-tools-abc123"}'