MCP Client

The MCP Client extension connects Mayros to external Model Context Protocol servers, bridging their tools into the Mayros tool system. Supports four transport protocols, automatic tool discovery, Cortex-backed registry, and OAuth2 authentication.

Architecture

mermaid
flowchart LR
    A[Mayros Agent] -->|call tool| B[Tool Bridge]
    B -->|route| C[Session Manager]
    C -->|transport| D[MCP Server]
    C -->|register| E[Cortex Registry]
    D -->|tools list| B

The Tool Bridge converts MCP tool descriptors into Mayros-native tools. The Session Manager handles connections, reconnection, and lifecycle. The Cortex Registry persists server and tool metadata for cross-session discovery.

Transports

Transport	Protocol	Use case
`stdio`	Spawns child process, JSON-RPC over stdin/stdout	Local tools, CLI wrappers
`http`	POST requests, JSON-RPC over HTTP	REST-based servers
`sse`	Server-Sent Events + POST	Streaming servers
`websocket`	Persistent WebSocket, bidirectional JSON-RPC	Real-time servers

All transports use JSON-RPC 2.0 with an initialization handshake (protocol_version: "2024-11-05").

Stdio

json5
{
  mcp: {
    servers: [{
      id: "my-local-tool",
      transport: {
        type: "stdio",
        command: "npx",
        args: ["-y", "@example/mcp-server"]
      }
    }]
  }
}

HTTP / SSE / WebSocket

json5
{
  mcp: {
    servers: [{
      id: "remote-server",
      transport: {
        type: "sse",           // or "http", "websocket"
        url: "https://api.example.com/mcp",
        authToken: "sk-..."   // optional static token
      },
      autoConnect: true
    }]
  }
}

Tool bridging

When a server connects, the Tool Bridge:

Lists available tools from the server
Classifies each tool's kind (read, write, exec, admin) based on name and description keywords
Converts JSON Schema parameters to TypeBox schemas
Registers tools in the Mayros tool system with an optional prefix

bash
# Tools appear as mcp_{serverId}_{toolName}
# e.g., mcp_github_list_repos

Tool kind classification

Kind	Keyword triggers
`read`	get, list, read, fetch, search, query, find, show, describe
`write`	create, update, delete, remove, set, put, post, write, modify, add
`exec`	run, exec, execute, invoke, call, start, stop, restart
`admin`	admin, manage, config, configure, deploy, install

OAuth2 authentication

For servers requiring OAuth2:

json5
{
  mcp: {
    servers: [{
      id: "cloud-service",
      transport: {
        type: "http",
        url: "https://api.example.com/mcp",
        oauth2: {
          clientId: "my-client-id",
          clientSecret: "my-secret",     // optional
          scopes: ["read", "write"],
          autoDiscover: true,            // discover endpoints from .well-known
          redirectPort: 8765             // local redirect port
        }
      }
    }]
  }
}

CLI commands for OAuth2 management:

bash
mayros mcp auth <serverId>      # Start OAuth2 flow
mayros mcp refresh <serverId>   # Refresh tokens
mayros mcp tokens               # List stored tokens
mayros mcp revoke <serverId>    # Remove stored tokens

Cortex registry

When registerInCortex is enabled (default), server and tool metadata is persisted as RDF triples:

{ns}:mcp:server:{serverId} → {ns}:mcp:serverName → "My Server"
{ns}:mcp:server:{serverId} → {ns}:mcp:transport → "sse"
{ns}:mcp:tool:{serverId}:{toolName} → {ns}:mcp:kind → "read"
{ns}:mcp:tool:{serverId}:{toolName} → {ns}:mcp:usageCount → "42"

Tool usage is tracked automatically via the after_tool_call hook, updating lastUsedAt and usageCount.

Reconnection

The Session Manager handles reconnection with exponential backoff:

Delay: reconnectDelayMs * 2^attempts
Max attempts: configurable (default: 5)
Auto-connect: servers with autoConnect: true connect on plugin start

Agent tools

Tool	Description
`mcp_connect`	Connect to a configured MCP server
`mcp_disconnect`	Disconnect from a server
`mcp_list_tools`	List available tools across servers
`mcp_call_tool`	Call a tool on a connected server

Configuration

json5
{
  mcp: {
    agentNamespace: "mayros",           // RDF namespace prefix
    registerInCortex: true,             // Persist in Cortex
    maxReconnectAttempts: 5,            // Max reconnection tries
    reconnectDelayMs: 3000,             // Base reconnect delay
    servers: [
      {
        id: "server-id",               // Unique identifier (alphanumeric + - _)
        name: "Human-readable name",
        transport: { /* see above */ },
        autoConnect: true,              // Connect on startup
        toolPrefix: "custom",           // Prefix for tool names
      }
    ]
  }
}

Skills Hub — skill marketplace
Cortex (AIngle) — RDF triple store
mcp CLI — command reference