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

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.

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.

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 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 assembles a dictionary named _TOOL_INDEX from the TOOL_DEFINITIONS list, which aggregates tool metadata from individual modules such as mcp/tools/extraction.py and 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.

python -m mcp

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

python -m mcp --debug

Example output showing successful startup:

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:

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

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:

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 — Core stdio server, JSON-RPC parsing, and request dispatch logic.
• mcp/tools/__init__.py — Aggregates TOOL_DEFINITIONS and builds _TOOL_INDEX.
• mcp/tools/extraction.py — Named entity recognition and relation extraction handlers.
• mcp/tools/graph.py — Entity creation, relationship management, and search tools.
• mcp/tools/decisions.py — Decision recording and querying utilities.
• mcp/tools/reasoning.py — Forward-chaining and abductive reasoning tools.
• mcp/tools/export.py — Graph export formats and provenance queries.
• mcp/resources/registry.py — URI-to-handler mapping for the four semantica:// resources.
• 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), dispatch (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 wraps all outputs consistently, ensuring clients receive structured error information alongside successful results.

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