MCP Server

The MCP Server extension turns Mayros into a Model Context Protocol server, exposing 9 tools, Cortex-backed resources, and agent prompts over stdio or HTTP. Any MCP-compatible client — Claude Desktop, Claude Code, VS Code, Cursor, or custom agents — can connect and use Mayros capabilities directly.

Architecture

mermaid
flowchart LR
    A[Claude Desktop] -->|stdio| B[MCP Server]
    C[Claude Code] -->|stdio| B
    D[Remote Agent] -->|HTTP| B
    B --> E[Memory Tools]
    B --> F[Budget Tools]
    B --> G[Governance Tools]
    B --> H[Cortex Tools]
    B --> I[Cortex Sidecar]
    I --> J[Ineru / Knowledge Graph]

The MCP Server starts a Cortex sidecar automatically, so memory, knowledge graph, and vector search are available immediately without manual setup.

Tools

The server exposes 9 tools organized in four categories:

Memory (4 tools)

Tool	Description
`mayros_remember`	Store information in persistent semantic memory with category, tags, and importance
`mayros_recall`	Search persistent memory by text, tags, or category
`mayros_search`	Vector similarity search over memory (HNSW-backed)
`mayros_forget`	Delete a specific memory entry by ID

Budget (1 tool)

Tool	Description
`mayros_budget`	Check token usage and budget status (session, daily, monthly spend)

Governance (1 tool)

Tool	Description
`mayros_policy_check`	Evaluate if an action is allowed by project governance policies

Cortex (3 tools)

Tool	Description
`mayros_cortex_query`	Query the semantic knowledge graph by subject/predicate/object patterns
`mayros_cortex_store`	Store facts as RDF triples in the knowledge graph
`mayros_memory_stats`	Get memory system statistics (Ineru STM/LTM, HNSW index, graph triples)

Resources and Prompts

Beyond tools, the server exposes MCP resources and prompts:

Resources — discovered Markdown agents, conventions, rules, graph statistics, graph subjects
Prompts — conventions, rules, and agent identity prompts for each discovered agent

Agents are automatically discovered from project (.mayros/agents/) and user (~/.mayros/agents/) directories.

Setup

Claude Desktop

The fastest way to register Mayros with Claude Desktop:

bash
mayros mcp-setup --desktop

This resolves absolute paths to node and mayros.mjs, then writes the configuration to claude_desktop_config.json. Restart Claude Desktop to activate.

For manual setup, add to your Claude Desktop config file:

json5
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%/Claude/claude_desktop_config.json
// Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "mayros": {
      "command": "/path/to/node",
      "args": ["/path/to/mayros.mjs", "serve", "--stdio"]
    }
  }
}

Claude Code

bash
mayros mcp-setup
# or manually:
claude mcp add mayros -- mayros serve --stdio

Other MCP clients (HTTP)

Start the server in HTTP mode:

bash
mayros serve --http
# default: http://127.0.0.1:19100/mcp

Then point your MCP client to http://127.0.0.1:19100/mcp.

Transports

Transport	Flag	Use case	Default port
stdio	`--stdio`	IDE integration, Claude Desktop	—
HTTP	`--http`	Remote clients, multi-agent setups	`19100`

If neither flag is specified, HTTP transport is used by default.

Configuration

json5
{
  mcpServer: {
    transport: "stdio",         // "stdio" or "http"
    port: 19100,                // HTTP port
    host: "127.0.0.1",          // HTTP bind address
    agentNamespace: "mayros",   // Cortex RDF namespace
    cortex: {
      port: 19090,              // Cortex sidecar port
    }
  }
}

Cortex sidecar

The mayros serve command auto-starts a Cortex sidecar when available. This provides:

Persistent semantic memory (Ineru STM/LTM)
HNSW vector search for similarity queries
RDF knowledge graph for structured facts
Data persistence at ~/.mayros/cortex-data/

The sidecar shuts down automatically when the MCP server stops.

Usage examples

Once connected, ask your client naturally:

"Remember that the deploy key rotates every 90 days"
→ calls mayros_remember

"What do you know about deploy keys?"
→ calls mayros_recall

"How much budget have I used today?"
→ calls mayros_budget

"Store that api-gateway depends on auth-service"
→ calls mayros_cortex_store

"Show memory statistics"
→ calls mayros_memory_stats

MCP Client — connect Mayros to external MCP servers
mcp CLI — MCP client command reference
serve CLI — mayros serve command reference
mcp-setup CLI — mayros mcp-setup command reference
Cortex — AIngle knowledge graph and memory backend