Q AI — MCP Server

The Q AI MCP (Model Context Protocol) server exposes 16 read-only tools that provide platform observability. These tools are designed for AI agents and LLMs to query the MEV engine without risk of state mutation.

Overview

The MCP server implements the Model Context Protocol standard, enabling any MCP-compatible client (Claude Desktop, Cursor, custom agents) to access YoorQuezt MEV platform data through structured tool calls.

All 16 tools are read-only -- they query the MEV engine and return structured data. No tool can modify engine state, submit transactions, or trigger any side effects.

How It Works

1. Client connects to the MCP server via stdio or HTTP transport.
2. Tool discovery -- the client requests the list of available tools and their schemas.
3. Tool invocation -- the client (or LLM) calls a tool with parameters.
4. Server executes the corresponding query against the MEV engine HTTP API.
5. Response returned as structured JSON to the client.

┌──────────────┐     MCP Protocol     ┌──────────────┐      HTTP       ┌──────────────┐
│  MCP Client  │ ──────────────────►  │  MCP Server  │ ──────────────► │  MEV Engine  │
│  (Claude,    │  tool call           │  (:9101)     │  GET /api/v1/.. │  (:8080)     │
│   Cursor,    │ ◄────────────────── │              │ ◄────────────── │              │
│   custom)    │  structured result   │              │  JSON response  │              │
└──────────────┘                      └──────────────┘                 └──────────────┘

Tools Reference

Error Codes

Error response format:

{
  "error": {
    "code": 1002,
    "message": "Bundle not found",
    "data": {
      "bundle_hash": "0xabc123...",
      "suggestion": "The bundle may have expired or was never submitted."
    }
  }
}

Configuration

Code Examples

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "yoorquezt": {
      "command": "yqmcp",
      "args": ["--engine-url", "http://localhost:8080"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Direct Tool Call (HTTP Transport)

# Start MCP server in HTTP mode
MCP_TRANSPORT=http MCP_PORT=9101 yqmcp

# Call a tool
curl -X POST http://localhost:9101/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "platform_health_summary",
      "arguments": {}
    }
  }'

Response Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"healthy\",\"uptime\":\"14d 3h 22m\",\"engine\":{\"status\":\"running\",\"version\":\"1.4.2\"},\"chains\":{\"connected\":11,\"total\":11},\"relays\":{\"active\":5,\"total\":5},\"bundles\":{\"pending\":3,\"landed_24h\":142},\"profit_24h\":\"2.847 ETH\"}"
      }
    ]
  }
}

TypeScript MCP Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "yqmcp",
  args: ["--engine-url", "http://localhost:8080"],
});

const client = new Client({ name: "my-app", version: "1.0.0" }, {});
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log("Available tools:", tools.tools.map(t => t.name));

// Call a tool
const result = await client.callTool({
  name: "get_order",
  arguments: { id: "0xbundle_hash" },
});
console.log("Bundle:", result.content);

Python MCP Client

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="yqmcp",
        args=["--engine-url", "http://localhost:8080"],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List tools
            tools = await session.list_tools()
            for tool in tools.tools:
                print(f"  {tool.name}: {tool.description}")

            # Call a tool
            result = await session.call_tool(
                "platform_health_summary", arguments={}
            )
            print("Health:", result.content)

asyncio.run(main())