mcp_overview.md

MCP overview

Scope

This document covers a curated overview of Neotoma MCP usage and links to canonical MCP references. It does not replace the full MCP specification or OAuth implementation details.

Purpose

Provide a single entry point for MCP documentation with links to setup guides, the MCP spec, and authentication references.

Invariants

1. MCP actions MUST follow the MCP specification.
2. MCP mutations MUST respect State Layer boundaries and explicit user control.
3. MCP examples MUST be deterministic and free of credentials.

Definitions

• MCP: Model Context Protocol used by AI tools to access Neotoma.
• Action catalog: The list of supported MCP actions and schemas.
• Setup guide: Tool specific instructions for MCP integration.

When to use CLI vs MCP

• Local (same machine as repo): Prefer the Neotoma CLI for all Neotoma operations. Invoke commands directly (e.g. neotoma entities list). The CLI is more reliable locally (no MCP server spawn/sync issues). Use MCP only if the user explicitly configures it.
• Remote (tunnel, ChatGPT, cloud): Use MCP over HTTP with the configured Neotoma URL (e.g. tunnel or neotoma.fly.dev).

For local development and agents running in the repo, the CLI is the recommended interface; MCP is recommended for remote clients.

Transport choice: stdio (local) vs HTTP (remote)

• Stdio: Use for local clients (Cursor, Claude Code, Codex on the same machine as the Neotoma repo). Client spawns the server; better recovery after sleep.
• HTTP: Use for remote access (tunnel, ChatGPT, deployed neotoma.fly.dev).

See setup guides for config examples and comparison table.

Canonical MCP documentation

• MCP specification: docs/specs/MCP_SPEC.md
• MCP server instructions (loaded at runtime): docs/developer/mcp/ — instructions.md, unauthenticated.md, tool_descriptions.yaml
• Cursor setup: docs/developer/mcp_cursor_setup.md
• ChatGPT setup: docs/developer/mcp_chatgpt_setup.md
• Claude Code setup: docs/developer/mcp_claude_code_setup.md
• OpenClaw setup: docs/developer/mcp_openclaw_setup.md
• Agent CLI config (unified MCP for Cursor, Claude Code, Codex): docs/developer/agent_cli_configuration.md
• OAuth implementation: docs/developer/mcp_oauth_implementation.md
• Authentication summary: docs/developer/mcp_authentication_summary.md

What MCP provides

MCP exposes structured actions for:

1. Storing structured data and files.
2. Retrieving entities, observations, relationships, and timeline events.
3. Correcting and reinterpreting observations.
4. Schema recommendations and updates.

Diagrams

flowchart TD
    aiTool[AITool] -->|"MCP action"| mcpServer[McpServer]
    mcpServer -->|"Validate and store"| stateLayer[TruthLayer]
    stateLayer -->|"Response"| mcpServer
    mcpServer -->|"MCP response"| aiTool

Loading

Examples

Storing: Use the structured path (store with entities) for conversation- or tool-sourced data; use the unstructured path (store with file_content/file_path) for file- or resource-sourced data. See MCP_SPEC section 2.6 for the full rule.

Store a structured entity

{
  "action": "store",
  "entities": [
    {
      "entity_type": "task",
      "title": "Review quarterly report",
      "status": "open"
    }
  ]
}

Store chat turn with batched relationships (preferred)

{
  "action": "store",
  "idempotency_key": "conversation-chat-12-1731680000000",
  "entities": [
    { "entity_type": "conversation", "title": "Inbox check" },
    {
      "entity_type": "agent_message",
      "role": "user",
      "content": "show me the emails in my inbox",
      "turn_key": "chat:12"
    },
    { "entity_type": "task", "title": "Follow up on invoice", "status": "open" }
  ],
  "relationships": [
    { "relationship_type": "PART_OF", "source_index": 1, "target_index": 0 },
    { "relationship_type": "REFERS_TO", "source_index": 1, "target_index": 2 }
  ]
}

Use one store call with a batched relationships array when the linked entities are in the same request. Reserve create_relationship for fallback cases or links that target entities outside the request (for example, EMBEDS to a file interpretation entity).

Store a file (unstructured)

{
  "action": "store",
  "idempotency_key": "file-invoice-001",
  "file_path": "/path/to/invoice.pdf",
  "mime_type": "application/pdf",
  "original_filename": "invoice.pdf"
}

Retrieve entities

{
  "action": "retrieve_entities",
  "entity_type": "task",
  "limit": 5,
  "offset": 0
}

Testing requirements

1. Verify MCP actions conform to docs/specs/MCP_SPEC.md.
2. Validate OAuth setup using the relevant setup guide.

Agent MCP behavior tests

Use the agent MCP behavior suite to validate that MCP instructions trigger the expected tool calls and stored entities.

Fixture matrix: tests/fixtures/agent_mcp_cases.json
Test entrypoint: tests/agent/mcp_instruction_behavior.test.ts
Command: npm run test:agent-mcp

Required environment for headless runners:

• AGENT_TEST_ENABLED=true to enable the suite
• AGENT_TEST_RUNNER=claude_code (default) or cursor_cli
• AGENT_CLI_COMMAND pointing to a wrapper command that reads:
  • AGENT_PROMPT_PATH (prompt file)
  • AGENT_ATTACHMENTS_PATH (JSON attachments list)
  • AGENT_TRACE_PATH (write NDJSON tool-call trace)

Trace format: Each NDJSON line must be JSON with at least:

{"tool":"store","arguments":{...},"result":{...}}

Agent Instructions

When to Load This Document

Load this document when providing MCP entry points or curating MCP documentation navigation.

Required Co-Loaded Documents

• docs/NEOTOMA_MANIFEST.md
• docs/specs/MCP_SPEC.md
• docs/conventions/documentation_standards.md

Constraints Agents Must Enforce

1. Links MUST point to canonical MCP docs.
2. Examples MUST be deterministic and credential free.
3. Terminology MUST match the MCP spec.

Forbidden Patterns

• Duplicating the MCP spec content in this overview
• Using real tokens or credentials in examples
• Omitting required sections

Validation Checklist

• Purpose, Scope, Invariants, Definitions present
• Links to MCP spec and setup guides included
• Examples are deterministic and credential free
• Agent Instructions included