How to Set Up the Semantica MCP Server for External Tool Integrations

The Semantica MCP server is a stdio-based JSON-RPC gateway that exposes the platform's knowledge graph, decision-intelligence engine, and reasoning tools to any MCP-compatible client through a simple pip install and a JSON configuration block.

Setting up the Model Context Protocol (MCP) server in the semantica-agi/semantica repository takes minutes and requires no network ports or API keys. The server runs as a local subprocess, registers twelve tool definitions from the mcp/tools/ package, and communicates via newline-delimited JSON-RPC on standard input and output. This guide covers installation, client-side configuration, and the core architecture you need to integrate Semantica with Claude Desktop, Cursor, VS Code, and other AI assistants.

Architecture of the Semantica MCP Server

The implementation is split into focused modules under the mcp/ directory. Each component handles a distinct layer of the stdio transport stack:

• semantica-mcp — The recommended CLI entry point that launches the server as a subprocess. It reads newline-delimited JSON-RPC requests on stdin and writes responses to stdout.
• SemanticaMCPServer (mcp/server.py) — Registers twelve tool definitions spanning extraction, decision-intelligence, graph manipulation, reasoning, and export, then runs the stdio event loop.
• mcp/session.py — Holds a singleton ContextGraph that stores nodes, edges, decisions, and provenance for the active session.
• mcp/schemas.py — Supplies JSON-Schema validation for every tool's input payload.
• mcp/tools/* — Concrete implementations located in extraction.py, decisions.py, graph.py, reasoning.py, and export.py.
• mcp/resources/registry.py — Exposes three read-only semantica:// URIs for graph summary, recent decisions, and schema info.

Key Design Characteristics

Several constraints make the server ideal for local AI assistant integrations:

• No network ports — Communication is exclusively stdio, so firewall rules and API keys are unnecessary.
• Local-only security — The process runs under the same user account as the AI client, inheriting OS file-system permissions.
• Optional persisted graph — Set the SEMANTICA_KG_PATH environment variable to an absolute JSON file path to retain the graph across restarts; otherwise it remains in memory only.

Installing and Launching the Server

Install Semantica with MCP Extras

From the root of the cloned repository, install the package including the MCP dependency group:

pip install -e ".[mcp]"

Start the Server

Use the semantica-mcp wrapper or invoke the module directly:

semantica-mcp

# or

python -m semantica.mcp_server

Both methods default to stdio transport and block until the parent AI client closes the pipe.

Configure Your AI Client for External Tool Integrations

Every MCP-compatible client needs a JSON block that tells it how to launch the subprocess. The block must contain:

• command — The binary name (semantica-mcp) or full path to the virtual-env binary.
• args — ["-m", "mcp"] if you invoke the server via python.
• cwd — The absolute directory where the Semantica repository lives.
• env (optional) — Variables such as SEMANTICA_KG_PATH and SEMANTICA_LOG_LEVEL.

Claude Desktop (~/.claude/settings.json)

{
  "mcpServers": {
    "semantica": {
      "command": "semantica-mcp",
      "env": {
        "SEMANTICA_KG_PATH": "/absolute/path/to/knowledge_graph.json",
        "SEMANTICA_LOG_LEVEL": "INFO"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "semantica": {
      "command": "semantica-mcp",
      "env": {
        "SEMANTICA_KG_PATH": "/absolute/path/to/knowledge_graph.json"
      }
    }
  }
}

VS Code (Cline / Continue) — .vscode/mcp.json

{
  "servers": {
    "semantica": {
      "type": "stdio",
      "command": "semantica-mcp",
      "env": {
        "SEMANTICA_KG_PATH": "${workspaceFolder}/knowledge_graph.json",
        "SEMANTICA_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Docker Deployment

You can also run the server in a container with attached volumes for persistence:

docker run --rm -i \
  -e SEMANTICA_KG_PATH=/data/kg.json \
  -v /local/absolute/path:/data \
  ghcr.io/semantica-agi/semantica-mcp:latest

Using MCP Tools from Natural Language

Once the client is connected, the LLM can invoke any of the twelve registered tools by describing the desired action in natural language. The server translates the request into a JSON-RPC call, executes the matching function in mcp/tools/, and returns structured JSON.

Employee Directory Example

Prompt the assistant with a task such as: “Extract entities from this meeting transcript about Alice transferring to Engineering, add them to the graph, and record a promotion decision.”

The AI chains the following tool calls internally:

extract_entities(text="Alice is transferring...")
add_entity(id="emp-alice", label="Alice", type="Employee")
add_entity(id="dept-eng", label="Engineering", type="Department")
add_relationship(source="emp-alice", target="dept-eng", type="WORKS_IN")
record_decision(category="promotion", scenario="Alice transferring to Engineering",
                reasoning="Approved by Engineering Director", outcome="transfer_approved",
                confidence=1.0)

All mutations occur in the live ContextGraph maintained by session.py, and the decision node captures provenance for later audit.

Core Source Files and Their Roles

The following files define the full lifecycle from launch to tool invocation to graph persistence, as implemented in semantica-agi/semantica:

• mcp/README.md — Overview, quick-start commands, transport description, and the complete tool list.
• docs/guides/mcp-server.md — Full user guide with client-specific configuration templates and troubleshooting steps.
• mcp/server.py — Implements SemanticaMCPServer and the stdio event loop.
• mcp/tools/extraction.py — NER and relation extraction logic backing extract_entities and extract_relations.
• mcp/tools/decisions.py — Decision-recording and query functions such as record_decision and query_decisions.
• mcp/tools/graph.py — Graph mutation utilities including add_entity, add_relationship, and analytics.
• mcp/tools/export.py — Multi-format export support (JSON, Turtle, RDF/XML, and others).
• mcp/resources/registry.py — Read-only semantica:// URI handlers for graph summary, decisions list, and schema metadata.

Summary

• The Semantica MCP server in semantica-agi/semantica is a stdio-only JSON-RPC gateway with no network ports or API keys.
• Install it with pip install -e ".[mcp]" and start it via the semantica-mcp CLI.
• Configure Claude Desktop, Cursor, VS Code, or Docker by supplying the command path and optional SEMANTICA_KG_PATH environment variable.
• The server registers twelve tools across extraction, decisions, graph operations, reasoning, and export, backed by files in mcp/tools/.
• Graph state is managed by session.py and can optionally persist to a JSON file between sessions.

Frequently Asked Questions

What is the primary entry point to start the Semantica MCP server?

The recommended entry point is the semantica-mcp command installed by the MCP extras, which wraps the stdio event loop defined in mcp/server.py. You can also invoke it directly with python -m semantica.mcp_server if you need to pass module-specific arguments.

How does the server persist data across restarts?

Set the SEMANTICA_KG_PATH environment variable to an absolute JSON file path before launching the server. When this variable is present, session.py serializes the ContextGraph to disk so nodes, edges, and decisions survive process restarts. Without it, the graph lives only in memory.

Which AI clients are compatible with the Semantica MCP server?

Any client that supports the Model Context Protocol over stdio can connect, including Claude Desktop, Cursor, Windsurf, Cline, VS Code / GitHub Copilot, Continue, and Amazon Q Developer. The repository provides ready-made JSON snippets for Claude Desktop, Cursor, and VS Code in docs/guides/mcp-server.md.

How many tools does the SemanticaMCPServer register?

The SemanticaMCPServer class in mcp/server.py registers twelve tool definitions at startup. These cover entity extraction, decision-intelligence, graph manipulation, reasoning, and multi-format export, with concrete implementations located in mcp/tools/extraction.py, mcp/tools/decisions.py, mcp/tools/graph.py, mcp/tools/reasoning.py, and mcp/tools/export.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}