# How to Integrate Semantica as an MCP Server for AI Agents

> Integrate Semantica as an MCP server for AI agents. Expose knowledge-graph operations via JSON-RPC 2.0 for seamless tool discovery and remote function invocation.

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

---

**Semantica provides a built-in MCP server that exposes knowledge-graph operations through JSON-RPC 2.0 over stdio, allowing any AI agent to discover and invoke graph tools as remote functions.**

The [semantica-agi/semantica](https://github.com/semantica-agi/semantica) repository ships with a complete **Model Context Protocol (MCP)** implementation. This lets Claude Code, Cursor, VS Code Copilot, and other MCP-compatible agents treat Semantica's knowledge-graph engine as a first-class tool provider without HTTP APIs or complex configuration.

## What Is the Semantica MCP Server?

Semantica's MCP server follows the [Model Context Protocol specification](https://modelcontextprotocol.io), using **JSON-RPC 2.0 messages over stdio**. The server runs as a long-lived subprocess: your AI agent writes requests to its stdin and reads responses from stdout.

**Key architectural components:**

- **Event loop** ([`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py)): Parses incoming JSON-RPC lines, dispatches to handlers, and serializes responses
- **Dispatch table** (`_DISPATCH`): Maps MCP methods (`initialize`, `tools/list`, `tools/call`) to handler functions
- **Tool registry** (`TOOL_DEFINITIONS` in [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py)): Aggregates discoverable tools with JSON schemas
- **Graph tools** ([`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py)): Implements `add_entity`, `add_relationship`, `search_graph`, `get_graph_summary`, `get_graph_analytics`
- **Session store** ([`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py)): Provides `get_graph()` singleton for in-memory or persistent graph instances

Each request flows through: parse → dispatch → execute → wrap → write. All responses include the standard `jsonrpc: "2.0"` envelope with either a `result` or `error` field.

## Starting the MCP Server

Launch Semantica's MCP server using Python's module execution:

```bash

# Standard start

python -m mcp

# With debug logging for troubleshooting

python -m mcp.server --debug

```

The server immediately enters a read loop on stdin, blocking until it receives valid JSON-RPC requests. Because it uses stdio, it runs anywhere you can spawn a subprocess with piped streams—Docker containers, VS Code extensions, Jupyter kernels, or CI pipelines.

## Discovering Available Tools

After initialization, an MCP client should call `tools/list` to discover capabilities. This returns all graph operations with their descriptions and input schemas.

Example request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

```

The server responds with tool definitions from [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py), including:

- `add_entity`: Create nodes with id, label, and type
- `add_relationship`: Connect entities with typed edges
- `search_graph`: Full-text or structured queries
- `get_graph_summary`: High-level statistics
- `get_graph_analytics`: Computed metrics and traversal results

Each tool includes a JSON Schema describing required and optional parameters, defined in [`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py).

## Invoking Graph Operations

Use `tools/call` with the target tool name and arguments. The server validates inputs against schemas, executes the handler from [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py), and returns structured content.

Example: adding an entity to the knowledge graph:

```json
{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "add_entity",
    "arguments": {
      "id": "alice",
      "label": "Alice",
      "type": "Person"
    }
  }
}

```

**Server response:**

```json
{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"id\":\"alice\",\"label\":\"Alice\",\"type\":\"Person\",\"created\":true}"
      }
    ],
    "isError": false
  }
}

```

Note that results are JSON-encoded strings inside the `text` field, following MCP's content array format.

## Minimal Python Client Example

This complete example demonstrates stdio-based communication with the Semantica MCP server:

```python
import json
import subprocess
import sys

# Start the MCP server subprocess

proc = subprocess.Popen(
    [sys.executable, "-m", "mcp.server"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
)

def rpc_call(method, params=None, req_id=1):
    """Send JSON-RPC request and return parsed response."""
    request = {
        "jsonrpc": "2.0",
        "id": req_id,
        "method": method,
        "params": params or {}
    }
    proc.stdin.write(json.dumps(request) + "\n")
    proc.stdin.flush()
    return json.loads(proc.stdout.readline())

# Discover available tools

print(rpc_call("tools/list"))

# Add a person entity

print(rpc_call("tools/call", {
    "name": "add_entity",
    "arguments": {"id": "bob", "label": "Bob", "type": "Person"}
}))

# Create a relationship

print(rpc_call("tools/call", {
    "name": "add_relationship",
    "arguments": {
        "source": "alice",
        "target": "bob",
        "type": "KNOWS"
    }
}))

# Search the graph

print(rpc_call("tools/call", {
    "name": "search_graph",
    "arguments": {"query": "Person", "limit": 10}
}))

```

The `rpc_call` helper implements the complete request-response cycle required by the MCP protocol.

## Integrating with VS Code Extensions

For TypeScript-based agent environments, spawn the server and communicate over stdio:

```typescript
import * as cp from 'child_process';

const proc = cp.spawn('python', ['-m', 'mcp.server']);

// Send a tool invocation
const request = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'get_graph_summary',
    arguments: {}
  }
};

proc.stdin.write(JSON.stringify(request) + '\n');

proc.stdout.on('data', (data) => {
  const response = JSON.parse(data.toString());
  if (response.result && !response.result.isError) {
    const summary = JSON.parse(response.result.content[0].text);
    // Use summary.vertex_count, summary.edge_count, etc.
  }
});

```

This pattern works identically in Cursor extensions, Claude Code plugins, or custom agent frameworks.

## Configuring Persistent Storage

By default, [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py) maintains the graph in memory for the process lifetime. To persist across restarts, implement a custom storage adapter:

1. Subclass or replace the session's graph provider in [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py)
2. Add SQLite, Neo4j, or file-based persistence
3. Set the custom backend before launching the server

The tool handlers in [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py) call `get_graph()` without knowing the underlying storage, so swapping implementations is transparent to MCP clients.

## Key Source Files for MCP Integration

| File | Purpose |
|------|---------|
| [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py) | Core event loop, dispatch table, request handling |
| [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py) | Tool registration and `TOOL_DEFINITIONS` aggregation |
| [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py) | Implementation of all graph manipulation tools |
| [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py) | Graph instance lifecycle and storage abstraction |
| [`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py) | JSON Schema definitions for tool parameters |
| [`mcp/__main__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/__main__.py) | Entry point for `python -m mcp` |

## Summary

Integrating Semantica as an MCP server enables any JSON-RPC-capable AI agent to manipulate knowledge graphs through standardized tool calls:

- Launch via `python -m mcp` for stdio-based operation
- Discover tools with `tools/list`, invoke with `tools/call`
- Core graph operations live in [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py)
- Session management in [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py) controls persistence
- Works in Docker, VS Code, Jupyter, or any subprocess-friendly environment

## Frequently Asked Questions

### What AI agents support Semantica's MCP server?

Any agent implementing the Model Context Protocol can connect. This includes Claude Code, Cursor, VS Code Copilot Chat, and custom agents built with MCP SDKs. The stdio transport is the most widely supported.

### How do I debug communication issues with the MCP server?

Start the server with `--debug` to enable verbose logging of all JSON-RPC messages. Verify your client sends newline-terminated JSON and properly flushes stdin. Check that responses are parsed as single lines—[`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py) uses line-buffered output.

### Can I extend Semantica with custom MCP tools?

Yes. Add new tool definitions to [`mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/__init__.py) and implement handlers in `mcp/tools/` submodules. Register them in `TOOL_DEFINITIONS` with proper JSON schemas from [`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py). The server automatically exposes new tools via `tools/list`.

### Is the graph data persisted between MCP server restarts?

Not by default—the graph lives in memory via [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py). To persist data, modify [`session.py`](https://github.com/semantica-agi/semantica/blob/main/session.py) to use a database backend (SQLite, Neo4j, etc.) before launching the server. The tool implementations remain unchanged.