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

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

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, extraction.py, graph.py, reasoning.py, and export.py.

Resource Registry: 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

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:

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:

# Recommended: module runner

python -m semantica_mcp.mcp

# Direct server invocation

python -m semantica_mcp.mcp.server

Enable verbose logging:

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:

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:

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

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

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

# /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:

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:

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

For VS Code, add to settings.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	Core SemanticaMCPServer class and JSON-RPC loop
semantica_mcp/mcp/__main__.py	Entry point for python -m semantica_mcp.mcp
semantica_mcp/mcp/resources/registry.py	Resource URI definitions and handlers
semantica_mcp/mcp/tools/__init__.py	Tool registry aggregation
semantica_mcp/mcp/tools/decisions.py	Decision-making tool implementations
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 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. 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.

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