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: "conversation_message", role: "user", sender_kind: "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.

What the server exposes at its root

A running Neotoma binds a handful of unauthenticated discovery and health endpoints at the host root alongside the MCP transport itself. These exist so agents, proxies, and operators can identify and probe the deployment without credentials.

• GET / - root landing. Content-negotiated: browsers get an HTML page with identity, harness-connect snippets (pre-filled with the actual host URL), and an index of neotoma.io documentation; send Accept: application/json for the same content as JSON, or Accept: text/markdown for a Markdown document. Default (no HTML/Markdown) is JSON. The content adapts to deployment mode: sandbox, personal tunnel, prod, or local.
• GET /robots.txt - mirrors the deployment mode. Sandbox and local instances disallow crawling; personal and prod allow it and can link an external sitemap via NEOTOMA_PUBLIC_DOCS_URL.
• GET /.well-known/mcp/server-card.json - MCP server card (name, version, capabilities).
• GET /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource - OAuth discovery documents.
• GET /server-info - runtime details (version, git sha, build timestamp).
• GET /health - liveness probe.
• GET /favicon.ico - site icon for browser tabs.
• In sandbox mode: GET /sandbox/terms (acceptable-use JSON), POST /sandbox/report, and GET /sandbox/report/status.

See Connect a remote Neotoma for per-harness snippets, and Hosted Neotoma for the mode comparison.

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.