# How to Deploy Semantica as an MCP Server: Complete Setup Guide

> Deploy Semantica as an MCP server with this comprehensive guide. Easily expose your knowledge graph and tools to clients using JSON-RPC. Start your setup now.

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

---

**Launch Semantica's MCP server with `python -m semantica_mcp.mcp --debug` to expose its knowledge graph and tools to any Model Context Protocol client via JSON-RPC over standard input/output.**

The **Semantica MCP server** is a lightweight JSON-RPC 2.0 service that lets AI assistants interact directly with your Semantica knowledge graph. This guide covers the complete deployment process using actual source code from the semantica-agi/semantica repository, including architecture details and runnable examples.

## What Is the Semantica MCP Server?

Semantica's **MCP (Model Context Protocol) server** implements the open MCP specification to bridge Semantica's semantic knowledge graph with AI coding assistants like Claude Code, VS Code Copilot, and Cursor. The server communicates via newline-delimited JSON-RPC 2.0 messages over standard input/output, making it portable across any environment that can spawn subprocesses.

According to the semantica-agi/semantica source code, the server exposes:

- **Tools**: Graph operations, reasoning, extraction, decisions, and exports
- **Resources**: Read-only URIs providing graph metadata and schema information
- **Live graph access**: Real-time queries and mutations against the knowledge base

## Core Architecture and Components

### Main Server Class: `SemanticaMCPServer`

The entry point in [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py) implements the JSON-RPC message loop. It reads requests from `stdin`, dispatches to handlers, and writes responses to `stdout`.

Key implementation details from lines 40–48:

- **Dispatch table** maps MCP method names (`initialize`, `tools/list`, `resources/read`, `tools/call`) to concrete handlers
- **Standard error codes**: `-32700` (parse), `-32601` (method not found), `-32602` (invalid params), `-32603` (internal error)
- **Debug logging** controlled via `--debug` flag

### Tool Registry: [`semantica_mcp/mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/__init__.py)

All available tools are aggregated in the `TOOL_REGISTRY` list, which the `tools/list` method returns to clients. Individual categories live in files like [`decisions.py`](https://github.com/semantica-agi/semantica/blob/main/decisions.py), [`extraction.py`](https://github.com/semantica-agi/semantica/blob/main/extraction.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).

### Resource Registry: [`semantica_mcp/mcp/resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/resources/registry.py)

Provides structured URIs including:
- `semantica://graph/summary` — entity and relationship counts
- `semantica://schema/info` — ontology and type definitions

### Session Management: [`semantica_mcp/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py)

The `get_graph()` function gives handlers a live reference to the underlying knowledge graph, enabling real-time queries without restarts.

## Installing and Starting the Server

### Prerequisites

Ensure Semantica is installed with MCP dependencies:

```bash
pip install semantica[mcp]

# or from source

git clone https://github.com/semantica-agi/semantica.git
cd semantica && pip install -e ".[mcp]"

```

### Command-Line Deployment

The package provides two equivalent entry points:

```bash

# Recommended: module runner

python -m semantica_mcp.mcp

# Direct server invocation

python -m semantica_mcp.mcp.server

```

Enable verbose logging:

```bash
python -m semantica_mcp.mcp --debug

```

On startup, the server writes `Semantica MCP server starting (stdio)` to `stderr`, then blocks waiting for JSON-RPC requests.

## Connecting a Python MCP Client

Deploy the server as a subprocess and communicate over pipes:

```python
import subprocess
import json
import sys

# Start the MCP server

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

def rpc(method, params=None, request_id=1):
    """Send JSON-RPC request and return parsed response."""
    request = {"jsonrpc": "2.0", "id": request_id, "method": method}
    if params is not None:
        request["params"] = params
    
    proc.stdin.write(json.dumps(request) + "\n")
    proc.stdin.flush()
    return json.loads(proc.stdout.readline())

# Initialize handshake

print(rpc("initialize"))

# List available tools

print(rpc("tools/list"))

```

### Reading Graph Resources

Query built-in resource URIs:

```python

# Get graph summary statistics

response = rpc("resources/read", {"uri": "semantica://graph/summary"})
summary = json.loads(response["result"]["contents"][0]["text"])
print(f"Entities: {summary['entity_count']}, Relations: {summary['relation_count']}")

```

### Calling MCP Tools

Invoke graph operations with typed arguments:

```python
response = rpc("tools/call", {
    "name": "search_graph",
    "arguments": {
        "query": "find all entities related to 'machine learning'"
    }
})
result_text = response["result"]["content"][0]["text"]

```

## Production Deployment Patterns

### Docker Container

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install ".[mcp]"
EXPOSE 8080  # Only if wrapping with TCP gateway

CMD ["python", "-m", "semantica_mcp.mcp"]

```

### Systemd Service

```ini

# /etc/systemd/system/semantica-mcp.service

[Unit]
Description=Semantica MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 -m semantica_mcp.mcp --debug
Restart=always
User=semantica
StandardInput=socket
StandardOutput=socket

[Install]
WantedBy=multi-user.target

```

### Custom TCP/WS Gateway

To expose over network instead of stdio, wrap the `SemanticaMCPServer.dispatch()` method:

```python
from semantica_mcp.mcp.server import SemanticaMCPServer
import asyncio
import websockets
import json

server = SemanticaMCPServer()

async def ws_handler(websocket):
    async for message in websocket:
        payload = json.loads(message)
        response = await server.dispatch(payload)
        await websocket.send(json.dumps(response))

asyncio.run(websockets.serve(ws_handler, "0.0.0.0", 8765))

```

## MCP Client Configuration Files

For Claude Code, create [`.claude/mcp.json`](https://github.com/semantica-agi/semantica/blob/main/.claude/mcp.json):

```json
{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "semantica_mcp.mcp"],
      "env": {}
    }
  }
}

```

For VS Code, add to [`settings.json`](https://github.com/semantica-agi/semantica/blob/main/settings.json):

```json
{
  "mcp.servers": {
    "semantica": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "semantica_mcp.mcp", "--debug"]
    }
  }
}

```

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py) | Core `SemanticaMCPServer` class and JSON-RPC loop |
| [`semantica_mcp/mcp/__main__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/__main__.py) | Entry point for `python -m semantica_mcp.mcp` |
| [`semantica_mcp/mcp/resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/resources/registry.py) | Resource URI definitions and handlers |
| [`semantica_mcp/mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/__init__.py) | Tool registry aggregation |
| [`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py) | Decision-making tool implementations |
| [`semantica_mcp/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py) | Graph session management via `get_graph()` |

## Summary

- **Deploy Semantica as an MCP server** using `python -m semantica_mcp.mcp [--debug]`
- The server implements JSON-RPC 2.0 over stdio per the MCP specification
- **Core components**: `SemanticaMCPServer` (dispatcher), tool registry, resource registry, and session graph access
- **Integration options**: Direct subprocess, Docker, systemd, or custom TCP/WS gateway
- **Client support**: Claude Code, VS Code, Cursor, and any MCP-compatible tool

## Frequently Asked Questions

### What protocol does Semantica's MCP server use?

The server implements **Model Context Protocol (MCP)** using JSON-RPC 2.0 messages over standard input/output. This follows the official MCP specification from Anthropic, ensuring compatibility with Claude Code, VS Code Copilot, and other MCP clients. Error codes (`-32700` through `-32603`) match standard JSON-RPC conventions.

### Can I run Semantica's MCP server over HTTP instead of stdio?

Yes, but requires a custom wrapper. The `SemanticaMCPServer.dispatch()` method in [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py) accepts any JSON-RPC payload and can be integrated into FastAPI, Flask, or WebSocket servers. The default stdio transport is designed for subprocess communication with local AI assistants.

### What tools and resources are available through the MCP interface?

Tools include **graph search**, **entity extraction**, **decision analysis**, **semantic reasoning**, and **export operations**—all aggregated in [`semantica_mcp/mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/__init__.py). Built-in resources expose `semantica://graph/summary` and `semantica://schema/info` for introspecting graph state without mutations.

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

Start the server with `--debug` to enable verbose logging to stderr. Verify the process starts correctly by checking for `Semantica MCP server starting (stdio)` output. Test basic connectivity with an `initialize` JSON-RPC call before attempting tool invocations. Ensure your client sends newline-delimited JSON and properly flushes stdin buffers after each request.