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

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

pip install -e ".[mcp]"

Launch the server from the repository root:

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, 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 file assembles the complete list of MCP tool definitions by importing from specialized modules like 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 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:

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

Cursor

Configure ~/.cursor/mcp.json:

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

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "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:

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:

{
  "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.

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

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