MCP Integration

Melious implements the Model Context Protocol (MCP) for seamless integration with AI agents. Connect Claude, custom agents, or other MCP-compatible clients to access Melious tools.

Overview

MCP enables AI applications to:

Discover available tools dynamically
Execute tools with structured parameters
Receive results in a standardized format

MCP Server

Connect AI clients to Melious tools via MCP protocol.

SSE Streaming

Real-time updates via Server-Sent Events.

JSON-RPC 2.0

Standard protocol for tool execution.

MCP Server Endpoints

Melious exposes an MCP server that AI clients can connect to:

Endpoint	Method	Description
`/v1/mcp/initialize`	POST	Initialize MCP session
`/v1/mcp/tools/list`	POST	List available tools
`/v1/mcp/tools/call`	POST	Execute a tool
`/v1/mcp/ping`	GET	Health check
`/v1/mcp/sse`	GET	Server-Sent Events stream
`/v1/mcp/jsonrpc`	POST	JSON-RPC 2.0 endpoint

Authentication

All MCP endpoints require an API key with kit.mcp scope:

Authorization: Bearer sk-mel-your-api-key-here

Initialize Session

POST /v1/mcp/initialize

Initialize an MCP session with protocol version and capabilities.

Request

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {}
  },
  "clientInfo": {
    "name": "my-ai-agent",
    "version": "1.0.0"
  }
}

Response

{
  "protocolVersion": "2024-11-05",
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  },
  "serverInfo": {
    "name": "melious-mcp-server",
    "version": "1.0.0"
  }
}

List Tools

POST /v1/mcp/tools/list

Retrieve all available tools with their schemas.

Request

{
  "cursor": null
}

Response

{
  "tools": [
    {
      "name": "web-search",
      "description": "Search the web for current information",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search query"
          },
          "max_results": {
            "type": "integer",
            "default": 10,
            "minimum": 1,
            "maximum": 50
          }
        },
        "required": ["query"]
      }
    },
    {
      "name": "scrape-url",
      "description": "Extract content from a URL as markdown",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "include_markdown": {
            "type": "boolean",
            "default": true
          }
        },
        "required": ["url"]
      }
    },
    {
      "name": "context7-mcp",
      "description": "Access library documentation via Context7",
      "inputSchema": {
        "type": "object",
        "properties": {
          "library": {
            "type": "string",
            "description": "Library name to search"
          },
          "topic": {
            "type": "string",
            "description": "Documentation topic"
          }
        },
        "required": ["library"]
      }
    }
  ],
  "nextCursor": null
}

Call Tool

POST /v1/mcp/tools/call

Execute a tool with provided arguments.

Request

{
  "name": "web-search",
  "arguments": {
    "query": "latest AI developments",
    "max_results": 5
  }
}

Response (Success)

{
  "content": [
    {
      "type": "text",
      "text": "[{\"title\": \"OpenAI Announces...\", \"url\": \"https://...\", \"snippet\": \"...\"}]"
    }
  ],
  "isError": false
}

Response (Error)

{
  "content": [
    {
      "type": "text",
      "text": "Error: Invalid query parameter"
    }
  ],
  "isError": true
}

JSON-RPC 2.0 Transport

For clients that prefer JSON-RPC, use the unified endpoint:

POST /v1/mcp/jsonrpc

List Tools Request

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

Call Tool Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "web-search",
    "arguments": {
      "query": "AI news"
    }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{"type": "text", "text": "..."}],
    "isError": false
  }
}

Server-Sent Events (SSE)

For real-time updates, connect to the SSE endpoint:

GET /v1/mcp/sse

JavaScript Example

const eventSource = new EventSource(
  'https://api.melious.ai/v1/mcp/sse',
  {
    headers: {
      'Authorization': 'Bearer sk-mel-your-api-key-here'
    }
  }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('MCP Event:', data);
};

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
};

Claude Desktop Integration

To use Melious tools in Claude Desktop, add to your MCP configuration:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "melious": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-client"],
      "env": {
        "MCP_SERVER_URL": "https://api.melious.ai/v1/mcp/jsonrpc",
        "MCP_API_KEY": "sk-mel-your-api-key-here"
      }
    }
  }
}

Keep your API key secure. Never commit configuration files with API keys to version control.

Python Client Example

import httpx
import json

class MeliousMCPClient:
    def __init__(self, api_key: str):
        self.base_url = "https://api.melious.ai/v1/mcp"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    async def initialize(self):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/initialize",
                headers=self.headers,
                json={
                    "protocolVersion": "2024-11-05",
                    "capabilities": {"tools": {}},
                    "clientInfo": {"name": "python-client", "version": "1.0.0"}
                }
            )
            return response.json()

    async def list_tools(self):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/tools/list",
                headers=self.headers,
                json={}
            )
            return response.json()

    async def call_tool(self, name: str, arguments: dict):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/tools/call",
                headers=self.headers,
                json={"name": name, "arguments": arguments}
            )
            return response.json()

# Usage
async def main():
    mcp = MeliousMCPClient("sk-mel-your-api-key-here")

    # Initialize session
    await mcp.initialize()

    # List available tools
    tools = await mcp.list_tools()
    print(f"Available tools: {[t['name'] for t in tools['tools']]}")

    # Execute a tool
    result = await mcp.call_tool("web-search", {"query": "Python tutorials"})
    print(f"Search results: {result}")

import asyncio
asyncio.run(main())

Available MCP Tools

Tools exposed via MCP include:

Tool	Description	Category
`web-search`	Search the web for information	Search
`scrape-url`	Extract content from URLs	Data
`context7-mcp`	Access library documentation via Context7	Code
`microsoft-learn-mcp`	Search Microsoft Learn documentation	Code
`svelte-mcp`	Access Svelte framework documentation	Code

Use tools/list to get the full list with schemas.

Error Codes

Code	Description
`KIT_TOOL_NOT_FOUND`	Requested tool doesn't exist
`VALIDATION_INVALID_VALUE`	Invalid parameter value
`KIT_EXECUTION_FAILED`	Tool execution error
`KIT_RATE_LIMIT_EXCEEDED`	Too many requests
`AUTH_INVALID_API_KEY`	Invalid or missing API key

Best Practices

Initialize first - Always call /initialize before using tools
Cache tool list - Tool schemas don't change frequently
Handle errors - Check isError field in responses
Use appropriate timeouts - Some tools may take longer
Respect rate limits - Implement backoff on 429 errors

MCP Integration

MCP Integration

Overview

MCP Server

SSE Streaming

JSON-RPC 2.0

MCP Server Endpoints

Authentication

Initialize Session

Request

Response

List Tools

Request

Response

Call Tool

Request

Response (Success)

Response (Error)

JSON-RPC 2.0 Transport

List Tools Request

Call Tool Request

Response Format

Server-Sent Events (SSE)

JavaScript Example

Claude Desktop Integration

macOS

Windows

Python Client Example

Available MCP Tools

Error Codes

Best Practices

See Also

On this page