# How to Set Up the MCP Server and Tools for Semantica: Complete Configuration Guide

> Learn how to set up the MCP server and tools for Semantica AGI. This guide provides complete configuration steps for seamless AI client integration.

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

---

**Semantica provides a modular Model Context Protocol (MCP) server that exposes 17 knowledge-graph tools and 4 read-only resources over stdio, installed via `pip install -e ".[mcp]"` and launched with `python -m mcp` for immediate integration with Claude Code, Cursor, Windsurf, and other AI clients.**

The `semantica-agi/semantica` repository ships a fully-featured MCP implementation that bridges any MCP-compatible client with Semantica’s knowledge graph capabilities. Setting up the MCP server and tools for Semantica enables AI assistants to perform entity extraction, graph traversal, decision intelligence, and provenance tracking through a standardized **JSON-RPC 2.0** interface over **stdio**.

## Installation and Prerequisites

Install Semantica with the MCP extras to obtain the server components and all tool dependencies.

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

```

The server relies on a single environment variable, `SEMANTICA_KG_PATH`, to locate the persisted graph. If unset, the server defaults to an in-memory graph, suitable for testing or ephemeral sessions.

```bash
export SEMANTICA_KG_PATH="/path/to/your/knowledge_graph.json"

```

## MCP Server Architecture

The implementation follows a three-layer architecture that separates transport concerns from business logic.

**Transport Layer** — [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py) implements the stdio JSON-RPC loop. It parses each incoming line, dispatches requests to the appropriate handler, and writes back responses.

**Dispatch Layer** — [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py) assembles a dictionary named `_TOOL_INDEX` from the `TOOL_DEFINITIONS` list, which aggregates tool metadata from individual modules such as [`mcp/tools/extraction.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/extraction.py) and [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py).

**Business Logic Layer** — The actual implementations reside in `mcp/tools/*.py` (17 tools covering extraction, decisions, graph manipulation, reasoning, and export) and `mcp/resources/*.py` (4 read-only resource handlers).

When a request arrives, the server looks up the method in a dispatch table (`_DISPATCH`) for instructions like `tools/call` or `resources/read`. For tool invocations, it locates the definition in `_TOOL_INDEX` and invokes the `_handler` function, returning a JSON-RPC response that always contains a content list and an `isError` flag when the result includes an `"error"` key.

## Launching the MCP Server

Start the server using the module entry point. By default, it communicates over stdio and awaits JSON-RPC commands.

```bash
python -m mcp

```

Enable verbose logging to debug request/response cycles during integration.

```bash
python -m mcp --debug

```

Example output showing successful startup:

```text
2026-08-18 12:00:00,000 semantica.mcp.server INFO Semantica MCP server starting (stdio)

```

## Configuring AI Clients

Point any MCP-compatible client to the server command and working directory. The following configuration snippet demonstrates setup for **Claude Code**:

```json
{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "/path/to/semantica"
    }
  }
}

```

This same pattern applies to Cursor, Windsurf, Cline, Continue, and VS Code Copilot, allowing these tools to discover and invoke the 17 Semantica tools natively.

## Using Tools and Resources Programmatically

You can interact with the server directly via subprocess for testing or custom integrations. The protocol requires writing JSON-RPC requests followed by newlines and reading line-delimited responses.

### Calling an Extraction Tool

The following Python example invokes `extract_entities` via the stdio transport:

```python
import json, subprocess, sys

proc = subprocess.Popen(
    [sys.executable, "-m", "mcp"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
)

request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "extract_entities",
        "arguments": {"text": "Alice visited Paris in 2023."}
    },
}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()

response = json.loads(proc.stdout.readline())
print(response["result"]["content"][0]["text"])

# => {"entities": [{"text": "Alice", "type": "PERSON"}, ...]}

```

### Reading Built-in Resources

Resources provide read-only snapshots of graph state. The `semantica://graph/summary` URI returns node and edge counts:

```python
request = {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "resources/read",
    "params": {"uri": "semantica://graph/summary"},
}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()

response = json.loads(proc.stdout.readline())
print(response["result"]["contents"][0]["text"])

# => {"nodeCount": 42, "edgeCount": 58, "typeBreakdown": {...}}

```

## Key Implementation Files

Understanding the source structure helps when debugging or extending the server:

- **[`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py)** — Core stdio server, JSON-RPC parsing, and request dispatch logic.
- **[`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py)** — Aggregates `TOOL_DEFINITIONS` and builds `_TOOL_INDEX`.
- **[`mcp/tools/extraction.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/extraction.py)** — Named entity recognition and relation extraction handlers.
- **[`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py)** — Entity creation, relationship management, and search tools.
- **[`mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/decisions.py)** — Decision recording and querying utilities.
- **[`mcp/tools/reasoning.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/reasoning.py)** — Forward-chaining and abductive reasoning tools.
- **[`mcp/tools/export.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/export.py)** — Graph export formats and provenance queries.
- **[`mcp/resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/resources/registry.py)** — URI-to-handler mapping for the four `semantica://` resources.
- **[`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py)** — JSON Schema definitions validating tool input payloads.

## Summary

- Install the server with `pip install -e ".[mcp]"` and set `SEMANTICA_KG_PATH` to target a persistent graph.
- Launch via `python -m mcp` (optionally with `--debug`); the server communicates over stdio using JSON-RPC 2.0.
- Configure clients like Claude Code or Cursor to execute the module command in the repository root.
- The architecture separates transport ([`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py)), dispatch ([`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py)), and business logic (`mcp/tools/*.py`).
- The server exposes **17 tools** (extraction, graph manipulation, reasoning, decisions, export) and **4 read-only resources** via the `tools/call` and `resources/read` JSON-RPC methods.

## Frequently Asked Questions

### How do I persist the knowledge graph between server restarts?

Set the `SEMANTICA_KG_PATH` environment variable to a file path before launching the server. If this variable is unset, the server initializes an in-memory graph that disappears when the process terminates.

### Which AI clients are compatible with the Semantica MCP server?

Any client implementing the Model Context Protocol can connect, including Claude Code, Cursor, Windsurf, Cline, Continue, and VS Code Copilot. Configuration requires specifying the `python -m mcp` command and the repository working directory.

### What is the difference between tools and resources in this implementation?

**Tools** (17 total) are executable functions defined in `mcp/tools/*.py` that perform mutations or computations, such as `extract_entities` or `add_relationship`, invoked via the `tools/call` JSON-RPC method. **Resources** (4 total) are read-only data sources defined in `mcp/resources/*.py` that expose graph state snapshots like `semantica://graph/summary`, accessed via `resources/read`.

### How does the server handle errors in tool execution?

When a tool handler returns a result containing an `"error"` key, the server sets the `isError` flag to `true` in the JSON-RPC response content list. The transport layer in [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py) wraps all outputs consistently, ensuring clients receive structured error information alongside successful results.