# How to Use the MCP Server for Tool Integration in AI Agents

> Learn how to use the MCP server for tool integration in AI agents. Connect tools like Claude Code and VS Code Copilot to Semantica's knowledge graph operations via a JSON-RPC 2.0 interface.

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

---

**The Semantica MCP server provides a **stdio‑based JSON‑RPC 2.0 interface** that lets AI assistants like Claude Code, Cursor, VS Code Copilot, and Continue invoke 17 built‑in tools for knowledge‑graph operations.**

This guide walks through integrating the **Model Context Protocol (MCP) server** from the [`semantica-agi/semantica`](https://github.com/semantica-agi/semantica) repository into your AI agent workflow. You'll learn how to start the server, configure clients, and invoke tools for entity extraction, decision recording, and graph analytics.

## Architecture of the Semantica MCP Server

The server follows the MCP specification using **stdin/stdout transport**, eliminating network overhead while maintaining interoperability across editors.

| Component | Purpose | Source Location |
|-----------|---------|---------------|
| `SemanticaMCPServer` | Runs the JSON‑RPC loop, parsing newline‑delimited requests | [`mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/server.py) |
| [`session.py`](https://github.com/semantica-agi/semantica/blob/main/session.py) | Provides a lazy singleton `ContextGraph` shared by all tools | [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py) |
| [`schemas.py`](https://github.com/semantica-agi/semantica/blob/main/schemas.py) | Defines JSON‑Schema for type‑safe RPC payloads | [`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py) |
| `tools/` | Package containing 17 registered tools (extraction, decisions, graph, reasoning, export) | `mcp/tools/` |
| [`resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/resources/registry.py) | Maps `semantica://` URIs to resource handlers | [`mcp/resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/resources/registry.py) |

The request flow works as follows:

1. **Agent** generates a tool call through its MCP client.
2. **Client** writes a JSON‑RPC object to the server's `stdin`.
3. **Server** validates the payload against [`schemas.py`](https://github.com/semantica-agi/semantica/blob/main/schemas.py).
4. **Dispatcher** resolves the tool name to an implementation in `tools/`.
5. **Tool** accesses the shared `ContextGraph` via `get_graph()` from [`session.py`](https://github.com/semantica-agi/semantica/blob/main/session.py).
6. **Response** returns through `stdout` to the client.

## Installing and Starting the MCP Server

Install Semantica with MCP extras and launch the server:

```bash

# From repository root

pip install -e ".[mcp]"

# Start the stdio-based server

python -m mcp

```

The server runs indefinitely, reading JSON‑RPC requests from `stdin` and writing responses to `stdout`. No network ports are required.

## Configuring AI Assistant Clients

### Claude Code Configuration

Add to `~/.claude/settings.json`:

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

```

This configuration tells Claude Code to spawn the Semantica MCP server as a subprocess and route tool calls through it.

### VS Code (Copilot) and Other Editors

Most MCP‑compatible editors use a similar structure. Specify the command, arguments, and working directory so the editor can spawn and communicate with the server process.

## Invoking MCP Tools from AI Agents

All 17 tools follow the same JSON‑RPC 2.0 format. The server validates inputs against schemas defined in [`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py) before execution.

### Recording a Decision

When an agent needs to capture a decision with full provenance:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "record_decision",
  "params": {
    "category": "loan_approval",
    "scenario": "Applicant wants $50k loan, 30% DTI",
    "reasoning": "Income and credit score meet policy",
    "outcome": "approved",
    "confidence": 0.93
  }
}

```

The server routes this to [`mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/decisions.py), where `record_decision` executes:

```python
from mcp.session import get_graph

def record_decision(category, scenario, reasoning, outcome, confidence):
    graph = get_graph()  # Singleton ContextGraph

    decision_id = graph.record_decision(
        category=category,
        scenario=scenario,
        reasoning=reasoning,
        outcome=outcome,
        confidence=confidence
    )
    return {"decision_id": decision_id}

```

The decision is persisted to the shared graph without explicit state management.

### Adding an Entity

To insert a new node into the knowledge graph:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "add_entity",
  "params": {
    "entity_id": "acme_corp",
    "entity_type": "Organization",
    "properties": {"name": "Acme Corp", "industry": "SaaS"}
  }
}

```

The `add_entity` tool in [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py) handles this:

```python
from mcp.session import get_graph

def add_entity(entity_id, entity_type, properties):
    graph = get_graph()
    graph.add_node(entity_id, entity_type, **properties)
    return {"status": "ok"}

```

### Querying Graph Summary

Agents can retrieve analytics without modifying state:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "get_graph_summary",
  "params": {}
}

```

Response includes node count, edge count, decision count, and type breakdown—useful for LLM context window management.

## Available MCP Tools in Semantica

The 17 tools are organized into five functional groups:

| Category | Tools | Source File |
|----------|-------|-------------|
| **Extraction** | `extract_entities`, `extract_relations`, `extract_triplets` | [`mcp/tools/extraction.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/extraction.py) |
| **Decision Intelligence** | `record_decision`, `query_decisions`, `get_decision_provenance` | [`mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/decisions.py) |
| **Graph Operations** | `add_entity`, `add_relation`, `search_graph`, `get_graph_summary`, `delete_node` | [`mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/graph.py) |
| **Reasoning** | `forward_chain`, `abductive_reasoning` | [`mcp/tools/reasoning.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/reasoning.py) |
| **Export & Provenance** | `export_graph`, `get_provenance`, `export_decisions` | [`mcp/tools/export.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/tools/export.py) |

Each tool name maps directly to a Python class or function in the corresponding source file.

## Accessing MCP Resources via URI Schema

Beyond tools, the server exposes **resources** through the `semantica://` URI scheme, defined in [`mcp/resources/registry.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/resources/registry.py):

| URI | Description |
|-----|-------------|
| `semantica://graph/summary` | Node/edge statistics and type distribution |
| `semantica://decisions/list` | Paginated decision history |
| `semantica://schema/info` | Current graph schema metadata |
| `semantica://ontology/schema` | Full ontology definition |

Resources are read‑only and useful for initializing agent context or validating graph state before operations.

## Stateful Graph Sessions with Singleton Pattern

The [`session.py`](https://github.com/semantica-agi/semantica/blob/main/session.py) module implements a **lazy singleton pattern** for `ContextGraph`:

```python

# mcp/session.py

_graph = None

def get_graph():
    global _graph
    if _graph is None:
        _graph = ContextGraph()
    return _graph

def reset_graph():
    global _graph
    _graph = None

```

This design ensures that multiple tool invocations within the same server process operate on **identical graph state** without explicit passing. Agents can chain operations—extract entities, record decisions, run reasoning—without losing context.

## Performance Characteristics

- **Zero network latency**: Stdio transport runs in‑process with the host application.
- **Shared memory**: The singleton `ContextGraph` avoids serialization overhead between tool calls.
- **Schema validation**: Input validation occurs before any graph mutation, preventing invalid states.

## Summary

- The **Semantica MCP server** implements the Model Context Protocol using **stdio JSON‑RPC 2.0** for universal editor compatibility.
- Install with `pip install -e ".[mcp]"` and run via `python -m mcp`.
- Configure clients like **Claude Code** or **VS Code** with a simple command‑and‑cwd specification.
- **17 tools** cover extraction, decisions, graph CRUD, reasoning, and export—all validated against [`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py).
- **Shared state** through [`session.py`](https://github.com/semantica-agi/semantica/blob/main/session.py)'s singleton `ContextGraph` enables complex multi‑step workflows without explicit state management.
- **Resources** at `semantica://` URIs provide read‑only graph introspection for agent context initialization.

## Frequently Asked Questions

### What MCP clients are compatible with Semantica?

Any client supporting **stdio transport** and **JSON‑RPC 2.0** works, including **Claude Code**, **Cursor**, **VS Code Copilot**, **Continue**, and **Windsurf**. The server implements the base MCP protocol without vendor‑specific extensions.

### How does tool state persist across multiple calls?

All tools access the same **`ContextGraph` singleton** via `get_graph()` in [`mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/session.py). This shared instance persists for the server's lifetime, enabling stateful workflows like entity extraction followed by relationship mapping and decision recording.

### Can I run multiple MCP servers for different projects?

Yes—each project requires a separate server process with its own **working directory** (`cwd` in client config). The singleton pattern is process‑scoped, so isolated projects maintain independent graph states.

### Where are tool input schemas defined?

All schemas live in **[`mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/mcp/schemas.py)**. The server validates every incoming RPC request against these JSON‑Schema definitions before dispatching to tool implementations, ensuring type safety and clear error messages for malformed inputs.