API Reference Overview

m1nd exposes the live MCP tool surface over JSON-RPC 2.0 via stdio. Every tool requires agent_id as a parameter. The exported MCP schema uses underscore-based canonical names such as trail_resume, perspective_start, and apply_batch. Use tools/list for the exact count in your current build.

The grouped pages below still keep historical prefixed anchors for stable links, but executable tools/call examples use the canonical bare names returned by tools/list.

Several tools now do more than return raw results. On the main structural flows you should expect some combination of:

• proof_state
• next_suggested_tool
• next_suggested_target
• next_step_hint

That matters for how you integrate m1nd into an agent loop: treat many responses as workflow guidance, not just data blobs.

Tool Index

Core Activation

Analysis

Memory, Trails, and Learning

Exploration

Perspectives

Lifecycle, Search, and Surgical

The grouped reference pages below still organize the surface by area, but the current best operational map is in help, the README tool table, and the live tools/list response.

Common Parameters

Every tool requires the agent_id parameter:

Agent IDs are free-form strings. Convention: use the agent’s name or role identifier (e.g. "jimi", "hacker-auth", "forge-build").

JSON-RPC Request Format

m1nd uses the MCP protocol over JSON-RPC 2.0 via stdio. All tool calls use the tools/call method.

Request structure

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
        "name": "activate",
    "arguments": {
      "agent_id": "jimi",
      "query": "session management"
    }
  }
}

Successful response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... pretty-printed JSON result ... }"
      }
    ]
  }
}

The text field contains the tool-specific output as a pretty-printed JSON string. Parse it to get the structured result.

Error response (tool execution error)

Tool execution errors are returned as MCP isError content, not as JSON-RPC errors. Many current errors are recovery-oriented and may include fields such as hint, workflow_hint, example, or suggested_next_step.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"error\": \"...\", \"hint\": \"...\", \"suggested_next_step\": \"...\" }"
      }
    ],
    "isError": true
  }
}

Error response (protocol error)

JSON-RPC protocol errors use standard error codes:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: bad_method"
  }
}

Error Codes

Tool-specific errors (node not found, perspective not found, lock ownership violation, etc.) are returned via isError: true in the content, not as JSON-RPC errors.

Transport

m1nd supports two stdio transport modes, auto-detected per message:

• Framed: Content-Length: N\r\n\r\n{json} – standard MCP/LSP framing. Used by Claude Code, Cursor, and most MCP clients.
• Line: {json}\n – one JSON object per line. Used by simple scripts and testing.

The server auto-detects which mode each incoming message uses and responds in the same mode.

Tool Name Normalization

The exported MCP schema uses underscore-based canonical names, but the server still accepts legacy transport aliases when possible:

• activate is canonical
• transport-prefixed aliases are accepted where normalization applies

If you are generating tool calls from an MCP client, prefer the canonical schema names returned by tools/list.

Protocol Handshake

Before calling tools, MCP clients perform a handshake:

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "m1nd-mcp", "version": "0.8.0" },
    "capabilities": { "tools": {} }
  }
}

Then list available tools:

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

This returns the full schema for the live tool surface with inputSchema for each entry. Treat tools/list as the source of truth for the exact count in your current build.