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

> Configure the Semantica MCP server for Claude Desktop, VS Code, and Cursor with a simple Python command. Integrate AI tools seamlessly without Docker or complex networking.

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

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`

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

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

```

The [`mcp/README.md`](https://github.com/semantica-agi/semantica/blob/main/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`

```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`](https://github.com/semantica-agi/semantica/blob/main/mcp.json) file to version control without hardcoding absolute paths. The configuration at [`mcp/README.md`](https://github.com/semantica-agi/semantica/blob/main/mcp/README.md) line 80 provides the canonical reference for this setup.

## Cursor Configuration

### Configuration File Location

**File:** `~/.cursor/mcp.json`

```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`](https://github.com/semantica-agi/semantica/blob/main/mcp/README.md) line 13.

## Installation and Verification

### Step 1: Install MCP Dependencies

From the repository root, install the MCP extras:

```bash
pip install -e ".[mcp]"

```

### Step 2: Test the Server Manually

```bash
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)

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

```

### Querying Decisions (VS Code)

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

```

### Searching the Graph (Cursor)

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

```

## Key Source Files for Reference

| File | Role |
|------|------|
| [`mcp/README.md`](https://github.com/semantica-agi/semantica/blob/main/mcp/README.md) | Overview of MCP server, transport, tools, and client configurations |
| [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/.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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/mcp/README.md).