# How to Set Up MCP Server Integration for External Tool Access in Semantica

> Integrate MCP server with Semantica for external tool access. Follow simple steps: install extras, launch the server, and configure your AI client for seamless integration.

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

---

**To set up MCP server integration in Semantica, install the `semantica[mcp]` extra, launch the stdio-based server with `python -m mcp`, and configure your AI client to invoke that command.**

Semantica ships with a built-in **Model Context Protocol (MCP) server** that exposes its knowledge-graph, decision-intelligence, and reasoning capabilities over a simple JSON-RPC 2.0 channel. This guide walks through the architecture, installation, and client configuration required to connect MCP-aware tools like Claude Code, Cursor, and VS Code Copilot to the Semantica repository.

## Architecture Overview

The MCP implementation consists of three core components that work together to provide seamless external tool access.

### SemanticaMCPServer Core

The `SemanticaMCPServer` class in [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py) (lines 45-78) handles the main request loop. It reads newline-delimited JSON-RPC requests from `stdin`, dispatches them to the appropriate tool handler, and writes JSON-RPC responses to `stdout`. This stdio-based design eliminates network ports and firewall concerns, making it ideal for local IDE integrations.

### Tool Registry

All available capabilities are aggregated in `TOOL_DEFINITIONS` inside [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py) (lines 13-20). This registry imports handlers from the `mcp/tools/` package, including modules for extraction, decision tracking, graph queries, reasoning, and data export.

### Lazy Graph Session

The `get_graph()` function in [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py) (lines 20-38) creates a singleton `ContextGraph` instance with advanced analytics enabled. On first use, it optionally loads a persisted graph from the `SEMANTICA_KG_PATH` environment variable, ensuring all tools share the same stateful knowledge base.

## Installation and Server Startup

Because the server runs as a plain Python process, setup requires only package installation and command invocation.

Install Semantica with the MCP extra using pip:

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

```

Launch the server from the repository root:

```bash
python -m mcp --debug

```

The `--debug` flag enables verbose logging. Once started, the server waits for JSON-RPC lines on `stdin` and responds on `stdout`. Verify the binary works by running `echo | python -m mcp`; the process should start without errors and wait for input.

## Server Implementation Details

Understanding the source code helps troubleshoot integration issues and extend functionality.

### Request Dispatch Logic

In [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py), the main loop parses incoming JSON and routes methods like `tools/list` or `tools/call` to the appropriate handlers. The server implements the MCP specification strictly, returning properly formatted JSON-RPC 2.0 responses with error handling for invalid parameters or missing tools.

### Tool Definitions Structure

The [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py) file assembles the complete list of MCP tool definitions by importing from specialized modules like [`mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/decisions.py). Each tool exposes a schema describing its inputs, allowing AI clients to discover capabilities dynamically without hardcoding function signatures.

### Session Management

The [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py) module ensures thread-safe access to the `ContextGraph`. When the first tool request arrives, `get_graph()` instantiates the graph singleton. If `SEMANTICA_KG_PATH` is set, it loads the persisted knowledge graph from that file path, maintaining state between server restarts.

## Client Configuration Examples

Connect MCP-compatible AI tools by adding a command entry that invokes `python -m mcp` with the working directory set to the repository location.

### Claude Code

Add the following to `~/.claude/settings.json`:

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

```

### Cursor

Configure `~/.cursor/mcp.json`:

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

```

### VS Code (GitHub Copilot)

Add to [`.vscode/mcp.json`](https://github.com/semantica-agi/semantica/blob/main/.vscode/mcp.json) in your workspace:

```json
{
  "servers": {
    "semantica": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

```

## Testing the Integration

Verify connectivity by sending a raw JSON-RPC request via Python:

```python
import json
import subprocess

request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
}

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

out, _ = proc.communicate(json.dumps(request) + "\n")
response = json.loads(out.strip())
print(json.dumps(response, indent=2))

```

A successful response lists available tools including `extract_entities`, `record_decision`, and graph query functions:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "extract_entities", "description": "...", "inputSchema": {} },
      { "name": "record_decision", "description": "...", "inputSchema": {} }
    ]
  }
}

```

## Summary

- **Install** the MCP extra with `pip install -e ".[mcp]"` to access the server components.
- **Launch** the stdio server using `python -m mcp` from the repository root; use `--debug` for troubleshooting.
- **Configure** clients like Claude Code, Cursor, or VS Code Copilot to invoke the Python module with the correct working directory.
- **Persist** knowledge graph state between sessions by setting the `SEMANTICA_KG_PATH` environment variable before starting the server.
- **Extend** functionality by adding new tools to the `mcp/tools/` package and registering them in [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py).

## Frequently Asked Questions

### What is the Model Context Protocol (MCP)?

The Model Context Protocol is an open standard that enables AI assistants to discover and invoke external tools through a standardized JSON-RPC interface. Semantica implements MCP over stdio, allowing any compatible client to access its knowledge graph and reasoning capabilities without network configuration or separate API servers.

### How do I persist graph data between server restarts?

Set the `SEMANTICA_KG_PATH` environment variable to a file path before launching the server. The `get_graph()` function in [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py) automatically loads the graph from this location on startup and saves state changes, ensuring continuity across sessions.

### Which AI clients support Semantica's MCP server?

Any MCP-aware client supporting stdio transport works with Semantica, including Claude Code, Cursor, Windsurf, Cline, Continue, VS Code Copilot, and Amazon Q Developer. The server requires only Python 3 and the `semantica[mcp]` package to run.

### How do I debug connection issues with the MCP server?

Start the server with the `--debug` flag to enable verbose logging of JSON-RPC requests and responses. Test the installation manually using the Python subprocess example to verify the server responds correctly to `tools/list` requests before configuring IDE integrations.