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

> Easily set up the Semantica MCP server for external tool integrations. Expose your knowledge graph and reasoning tools via this JSON-RPC gateway. Learn how to connect with Semantica.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py)** — Holds a singleton `ContextGraph` that stores nodes, edges, decisions, and provenance for the active session.
- **[`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py)** — Supplies JSON-Schema validation for every tool's input payload.
- **`mcp/tools/*`** — Concrete implementations located in [`extraction.py`](https://github.com/semantica-agi/semantica/blob/main/extraction.py), [`decisions.py`](https://github.com/semantica-agi/semantica/blob/main/decisions.py), [`graph.py`](https://github.com/semantica-agi/semantica/blob/main/graph.py), [`reasoning.py`](https://github.com/semantica-agi/semantica/blob/main/reasoning.py), and [`export.py`](https://github.com/semantica-agi/semantica/blob/main/export.py).
- **[`mcp/resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/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:

```bash
pip install -e ".[mcp]"

```

### Start the Server

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

```bash
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`)

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

```

### Cursor (`~/.cursor/mcp.json`)

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

```

### VS Code (Cline / Continue) — [`.vscode/mcp.json`](https://github.com/semantica-agi/semantica/blob/main/.vscode/mcp.json)

```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:

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/mcp/README.md)** — Overview, quick-start commands, transport description, and the complete tool list.
- **[`docs/guides/mcp-server.md`](https://github.com/semantica-agi/semantica/blob/main/docs/guides/mcp-server.md)** — Full user guide with client-specific configuration templates and troubleshooting steps.
- **[`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py)** — Implements `SemanticaMCPServer` and the stdio event loop.
- **[`mcp/tools/extraction.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/extraction.py)** — NER and relation extraction logic backing `extract_entities` and `extract_relations`.
- **[`mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/decisions.py)** — Decision-recording and query functions such as `record_decision` and `query_decisions`.
- **[`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py)** — Graph mutation utilities including `add_entity`, `add_relationship`, and analytics.
- **[`mcp/tools/export.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/export.py)** — Multi-format export support (JSON, Turtle, RDF/XML, and others).
- **[`mcp/resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/docs/guides/mcp-server.md).

### How many tools does the SemanticaMCPServer register?

The `SemanticaMCPServer` class in [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/extraction.py), [`mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/decisions.py), [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py), [`mcp/tools/reasoning.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/reasoning.py), and [`mcp/tools/export.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/export.py).