How to Configure the Semantica MCP Server for Claude Desktop, VS Code, and Cursor

To configure the Semantica MCP server for Claude Desktop, VS Code, or Cursor, you define a stdio-based JSON-RPC connection using a python -m mcp command with the repository root as the working directory—no Docker or networking setup required.

The Semantica MCP (Model Context Protocol) server exposes the full Semantica knowledge-graph, decision-intelligence, extraction, and reasoning capabilities as a stdio-based JSON-RPC service. Because the server runs as a simple command-line process, any AI client that supports MCP can connect by supplying a command (the executable) together with optional arguments and a working directory. This article covers the exact configuration files needed for Claude Desktop, VS Code with GitHub Copilot, and Cursor.

MCP Server Architecture

The server is implemented in the mcp/ package within the Semantica repository:

mcp/
├── __init__.py          # re-exports SemanticaMCPServer + entry point

├── __main__.py          # python -m mcp entry point

├── server.py            # SemanticaMCPServer class + stdio event loop

├── session.py           # lazy singleton ContextGraph

├── schemas.py           # JSON-Schema definitions for tool inputs

└── tools/               # 17 MCP tools (extraction, decisions, graph, reasoning, export)

In mcp/server.py, the SemanticaMCPServer class implements the stdio event loop that handles JSON-RPC communication. The server exposes 17 tools organized into categories: extraction, decisions, graph operations, reasoning, and export utilities.

Core Configuration Structure

All integrations share the same three-field configuration:

Field	Meaning
command	The executable that starts the server (normally python)
args	Arguments passed to the command—["-m", "mcp"] runs the module
cwd	The working directory where Semantica is installed (repository root)

Replace /path/to/semantica with the absolute path to your cloned repository, or use a virtual-environment-aware path like $(poetry env info --path) if using Poetry.

Claude Desktop Configuration

Configuration File Location

File: ~/.claude/settings.json

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

Alternative CLI Setup

Claude Desktop provides a built-in command for adding MCP servers:

claude mcp add semantica python -m mcp --cwd /path/to/semantica

The mcp/README.md at line 92 documents this configuration pattern, noting that Claude launches the server process automatically when needed and manages the stdio connection internally.

VS Code (GitHub Copilot) Configuration

Configuration File Location

File: <workspace>/.vscode/mcp.json

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

VS Code supports the ${workspaceFolder} placeholder, which automatically resolves to the folder opened in the editor. This allows you to commit the mcp.json file to version control without hardcoding absolute paths. The configuration at mcp/README.md line 80 provides the canonical reference for this setup.

Cursor Configuration

Configuration File Location

File: ~/.cursor/mcp.json

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

Cursor reads this file on startup and lists defined MCP servers in its tool palette. Once configured, you can invoke any of the 17 Semantica tools directly from the editor interface. The Cursor-specific documentation appears at mcp/README.md line 13.

Installation and Verification

Step 1: Install MCP Dependencies

From the repository root, install the MCP extras:

pip install -e ".[mcp]"

Step 2: Test the Server Manually

python -m mcp

This opens a REPL where you can type JSON-RPC requests and press Enter to verify the server responds correctly.

Step 3: Verify Client Integration

Open the MCP tool palette in your chosen client:

• Claude Desktop: Look for "semantica" in the server list
• VS Code: Check the Copilot chat panel for MCP tools
• Cursor: Open the command palette and search for MCP servers

Selecting the server should display available tools like extract_entities, record_decision, add_entity, search_graph, and others defined in mcp/tools/.

Troubleshooting Common Issues

Symptom	Cause	Solution
Server does not appear in client	command path incorrect	Verify which python resolves to a working interpreter
Import errors on startup	cwd points to wrong directory	Ensure cwd is the Semantica repository root containing mcp/
Tools list empty	MCP extras not installed	Run pip install -e ".[mcp]"
Connection timeout	Python environment issues	Test manually with python -m mcp first

Example Tool Invocations

Once configured, clients automatically send JSON-RPC calls. Here are representative payloads:

Adding an Entity (Claude Desktop)

{
  "tool": "add_entity",
  "params": {
    "label": "Mars",
    "type": "Planet",
    "properties": {"radius_km": 3389.5}
  }
}

Querying Decisions (VS Code)

{
  "tool": "query_decisions",
  "params": {
    "query": "What was the rationale behind the 2024 product roadmap?"
  }
}

Searching the Graph (Cursor)

{
  "tool": "search_graph",
  "params": {
    "search_term": "neural"
  }
}

Key Source Files for Reference

File	Role
mcp/README.md	Overview of MCP server, transport, tools, and client configurations
mcp/server.py	SemanticaMCPServer class and stdio event loop implementation
mcp/tools/*.py	Individual tool implementations for extraction, decisions, graph, and reasoning
mcp/resources/registry.py	semantica:// read-only resource handlers

Summary

• Semantica MCP server runs as a stdio-based JSON-RPC process requiring no network configuration
• Three configuration files cover all major clients: ~/.claude/settings.json, .vscode/mcp.json, and ~/.cursor/mcp.json
• Core fields are command (python), args (["-m", "mcp"]), and cwd (repository root)
• 17 tools become available across all clients once connected
• Manual testing with python -m mcp validates installation before client integration

Frequently Asked Questions

Does the Semantica MCP server require Docker or network ports?

No. The server uses stdio transport, meaning the client launches it as a local subprocess and communicates over standard input/output. No containerization, port binding, or network configuration is needed as implemented in mcp/server.py.

Can I use a Python virtual environment with the MCP server?

Yes. Set command to the absolute path of your virtual environment's Python binary, or use shell expansion like "$(poetry env info --path)/bin/python" for Poetry-managed environments. Ensure cwd still points to the Semantica repository root.

How do I know if the server is working correctly?

Test manually by running python -m mcp from the repository root. If you see a JSON-RPC prompt, the server starts correctly. Then check your client's MCP tool palette for the "semantica" server with all 17 tools listed. If tools appear but fail, verify the cwd path contains the full Semantica source including mcp/tools/.

What Semantica features are exposed through MCP?

All major capabilities: entity extraction (extract_entities), decision recording and querying (record_decision, query_decisions), graph operations (add_entity, search_graph, traverse_graph), reasoning (infer_relations, evaluate_decision), and export utilities (export_graph, import_graph). The complete list is defined in mcp/tools/ and documented in mcp/README.md.

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