Model Context Protocol (MCP) server

Neotoma exposes 30 MCP actions covering storage, retrieval, relationships, schema management, corrections, and lifecycle. MCP is the primary interface for agent workflows because it keeps deterministic state operations explicit: retrieve before reasoning, store with provenance, and create typed relationships.

Transport modes

• stdio - local process, recommended for Cursor / Claude Code / Codex. The MCP client launches the Neotoma process directly.
• HTTP (SSE) - remote or tunnel access via http://localhost:3080/mcp (dev) or http://localhost:3180/mcp (prod). Use with --tunnel for HTTPS via ngrok or Cloudflare.
• WebSocket - bridge mode for clients that require WebSocket transport.

Client configuration

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "neotoma-dev": {
      "command": "/absolute/path/to/neotoma/scripts/run_neotoma_mcp_stdio.sh"
    },
    "neotoma": {
      "command": "/absolute/path/to/neotoma/scripts/run_neotoma_mcp_stdio_prod.sh"
    }
  }
}

Claude Code (claude_desktop_config.json) and Windsurf (mcp_config.json) use the same structure. Run neotoma mcp check to scan for config files and auto-install missing entries. Add --user-level to include user-level paths.

HTTP / tunnel (remote access):

{
  "mcpServers": {
    "neotoma": {
      "url": "http://localhost:3080/mcp"
    }
  }
}

Authentication

All MCP actions operate under an authenticated user context. Authentication is handled via OAuth (recommended) or Bearer token. The user_id parameter is optional and inferred from the auth context. Run neotoma auth login for OAuth setup, or set NEOTOMA_BEARER_TOKEN for token-based auth.

Common action patterns

# 1) Retrieve target entities before writing
retrieve_entity_by_identifier(identifier="Ana Rivera", entity_type="contact")

# 2) Store conversation + message + extracted entities in one call
store_structured(
  entities=[
    { entity_type: "conversation", title: "Project sync" },
    { entity_type: "agent_message", role: "user", content: "...", turn_key: "conv:1" }
  ],
  relationships=[{ relationship_type: "PART_OF", source_index: 1, target_index: 0 }],
  idempotency_key="conversation-conv-1-1711900000000"
)

# 3) Link entities explicitly
create_relationship(
  relationship_type="REFERS_TO",
  source_entity_id="<message_id>",
  target_entity_id="<task_id>"
)

# 4) Store a file with entities in one combined call
store(
  entities=[...],
  file_path="/path/to/invoice.pdf",
  idempotency_key="store-invoice-1711900000000"
)

# 5) Parse a file without storing (agent-side extraction)
parse_file(file_path="/path/to/document.pdf")

Schema management workflow

Schemas evolve automatically. Fields not in the current schema are stored in raw_fragments. High-confidence fields are auto-promoted. Manual workflow:

1. list_entity_types(keyword="invoice") - discover existing schemas
2. analyze_schema_candidates(entity_type="invoice") - see what fields are candidates
3. update_schema_incremental(entity_type="invoice", new_fields=[...]) - promote fields

Relationship types

Supported relationship types for create_relationship: PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, EMBEDS. Use EMBEDS when a container (blog post, document) embeds an asset (image, attachment): source = container, target = asset.

Entity types

Common types agents can set directly: contact, person, company, task, invoice, transaction, receipt, note, contract, event, conversation, agent_message. Codebase types: feature_unit, release, agent_decision, agent_session, validation_result, codebase_entity, architectural_decision. Use list_entity_types to discover all available types or store with any descriptive type and the server infers the schema.

Continue with REST API reference, CLI reference, agent instructions, and schema management.