# How to Integrate with Semantica Using the MCP Server: A Complete Guide

> Learn to integrate with Semantica using the MCP server. This guide shows how to start the JSON-RPC server and use MCPClient to add entities, create relationships, and query the knowledge graph.

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

---

**To integrate with Semantica using the MCP server, start the JSON‑RPC server via `python -m semantica_mcp.mcp`, then connect with the `MCPClient` class to call tools for adding entities, creating relationships, and querying the knowledge graph.**

Semantica provides a **Model-Context-Protocol (MCP) server** that enables language-agnostic integration with its knowledge graph. The server implements JSON-RPC 2.0 over standard input/output, making it compatible with Claude Code, Cursor, VS Code Copilot, and custom applications. This article walks through the complete integration workflow based on the semantica-agi/semantica source code.

## How the MCP Server Architecture Works

The MCP integration consists of five core components. Understanding their roles helps you choose the right approach for your use case.

| Component | Role | Source File |
|-----------|------|-------------|
| **MCP Server** | Dispatches JSON-RPC methods (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`) and manages the event loop | [`semantica_mcp/mcp/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/server.py) |
| **Tool Registry** | Aggregates tool definitions from all `mcp/tools/*` modules and exposes them via `tools/list` | [`semantica_mcp/mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/__init__.py) |
| **Graph Tools** | Handles entity and relationship operations, search, analytics, and persistence | [`semantica_mcp/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/graph.py) |
| **MCP Client (Python)** | Formats JSON-RPC calls with safe redirect handling and authentication stripping | [`semantica/ingest/mcp_client.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/mcp_client.py) |
| **MCP Ingestor** | Fetches resources from remote MCP servers and feeds them into Semantica pipelines | [`semantica/ingest/mcp_ingestor.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/mcp_ingestor.py) |

## Starting the MCP Server

The server entry point is `semantica_mcp.mcp`. Launch it from your terminal:

```bash
python -m semantica_mcp.mcp

```

Alternatively, invoke the server module directly:

```bash
python -m semantica_mcp.mcp.server

```

The server initializes logging and logs its startup status:

```python
log.info("Semantica MCP server starting (stdio)")

```

By default, the server listens on **stdio**. For HTTP deployment, configure your environment or proxy accordingly.

## Connecting with the Python MCPClient

The `MCPClient` class in [`semantica/ingest/mcp_client.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/mcp_client.py) provides the primary interface for Python applications. Instantiate it with either an HTTP endpoint or stdio transport:

```python
from semantica.ingest.mcp_client import MCPClient

# HTTP endpoint

client = MCPClient(url="http://localhost:8000/mcp")

# Standard input/output (for subprocess communication)

# client = MCPClient(url="stdio")

```

The client handles request formatting, safe redirect enforcement, and authentication header stripping automatically.

## Discovering Available MCP Tools

Before invoking operations, retrieve the complete tool catalog:

```python
tools = client.call(method="tools/list")
print(tools)

```

This returns tool names, descriptions, and JSON Schema input definitions. The tool definitions are aggregated in [`semantica_mcp/mcp/tools/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/__init__.py) via the `TOOL_DEFINITIONS` constant.

## Adding Entities to the Knowledge Graph

Use the `graph/add_entity` tool to create nodes. The server validates the request, updates the in-memory `ContextGraph`, and persists to disk when `SEMANTICA_KG_PATH` is configured:

```python
result = client.call(
    method="tools/call",
    params={
        "name": "graph/add_entity",
        "arguments": {
            "id": "acme_corp",
            "label": "Acme Corporation",
            "type": "Organization",
            "metadata": {"industry": "SaaS"}
        }
    }
)

```

The underlying handler `handle_add_entity` in [`semantica_mcp/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/graph.py) fetches the current graph via `get_graph()`, performs the mutation, and triggers persistence.

## Creating Relationships Between Entities

Connect entities with the `graph/add_relationship` tool:

```python
client.call(
    method="tools/call",
    params={
        "name": "graph/add_relationship",
        "arguments": {
            "source": "alice_chen",
            "target": "acme_corp",
            "type": "works_for",
            "metadata": {"since": "2019-03-01"}
        }
    }
)

```

The `handle_add_relationship` function validates source and target existence before creating the edge.

## Querying the Knowledge Graph

Search for entities using the `graph/search_graph` tool:

```python
search = client.call(
    method="tools/call",
    params={
        "name": "graph/search_graph",
        "arguments": {"query": "Acme", "limit": 5}
    }
)
print(search["results"])

```

This executes `handle_search_graph` which performs label and metadata matching against the current graph state.

## Running Graph Analytics

Compute centrality, PageRank, and community detection metrics:

```python
analytics = client.call(
    method="tools/call",
    params={
        "name": "graph/get_graph_analytics",
        "arguments": {"metrics": ["pagerank", "betweenness"], "top_n": 10}
    }
)

```

Available metrics depend on the networkx implementations in `handle_get_graph_analytics`.

## Exporting Knowledge Graph Data

Export to multiple formats using the export tools:

```python

# RDF Turtle export

export = client.call(
    method="tools/call",
    params={
        "name": "export/export_kg",
        "arguments": {"format": "turtle", "output_path": "/tmp/kg.ttl"}
    }
)

```

Supported formats include RDF, JSON-LD, and Parquet.

## Persisting Graph State Across Restarts

Set the `SEMANTICA_KG_PATH` environment variable before starting the server:

```bash
export SEMANTICA_KG_PATH=/path/to/graph.json
python -m semantica_mcp.mcp

```

The server:
1. Loads the existing graph from this path on startup via `get_graph()`
2. Automatically calls `graph.save_to_file()` after each mutating operation
3. Skips persistence if `is_persistence_safe()` detects a load failure

## Complete Integration Example

This pattern demonstrates end-to-end MCP server integration:

```python
from semantica.ingest.mcp_client import MCPClient

# 1. Connect to running server

client = MCPClient(url="http://localhost:8000/mcp")

# 2. Ingest domain data as entities

client.call("tools/call", {
    "name": "graph/add_entity",
    "arguments": {"id": "order_123", "label": "Order #123", "type": "Order"}
})

client.call("tools/call", {
    "name": "graph/add_entity",
    "arguments": {"id": "customer_456", "label": "Jane Smith", "type": "Customer"}
})

# 3. Establish relationships

client.call("tools/call", {
    "name": "graph/add_relationship",
    "arguments": {
        "source": "order_123",
        "target": "customer_456",
        "type": "placed_by"
    }
})

# 4. Query for contextual answers

response = client.call("tools/call", {
    "name": "graph/search_graph",
    "arguments": {"query": "order", "limit": 3}
})
print(response["results"])

```

## Advanced: Using MCPIngestor for Pipeline Integration

For automated data ingestion, use `MCPIngestor` from [`semantica/ingest/mcp_ingestor.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/mcp_ingestor.py):

```python
from semantica.ingest.mcp_ingestor import MCPIngestor

ingestor = MCPIngestor(mcp_url="http://localhost:8000/mcp")
resources = ingestor.ingest_from_uri("mcp://resource/path")

```

The `MCPIngestor` creates `MCPResource` objects, reads content via `MCPClient`, and returns raw data for downstream Semantica processing pipelines.

## Summary

- **Start the server** with `python -m semantica_mcp.mcp` for stdio-based JSON-RPC communication
- **Connect via `MCPClient`** using HTTP endpoints or stdio transport
- **Discover tools** with `tools/list` before invoking operations
- **Mutate the graph** using `graph/add_entity` and `graph/add_relationship` tools
- **Query and analyze** with `graph/search_graph` and `graph/get_graph_analytics`
- **Enable persistence** by setting `SEMANTICA_KG_PATH` before server startup
- **Automate ingestion** using `MCPIngestor` for pipeline-based workflows

## Frequently Asked Questions

### What protocols does the Semantica MCP server support?

The server implements **JSON-RPC 2.0** over standard input/output. This protocol enables any language or tool that speaks MCP—including Claude Code, Cursor, and VS Code Copilot—to interact with Semantica's knowledge graph without language-specific SDKs.

### How do I enable automatic graph persistence?

Set the `SEMANTICA_KG_PATH` environment variable to a file path before starting the server. The server loads from this path on startup and automatically persists mutations after each operation, provided `is_persistence_safe()` validates the load state.

### Can I use the MCP server from languages other than Python?

Yes. The MCP server uses JSON-RPC over stdio, which any language can implement. While Python developers use `MCPClient` from [`semantica/ingest/mcp_client.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/ingest/mcp_client.py), JavaScript, Go, Rust, or other languages can format equivalent JSON-RPC requests directly.

### What is the difference between MCPClient and MCPIngestor?

**`MCPClient`** is a low-level JSON-RPC client for direct tool invocation. **`MCPIngestor`** is a higher-level abstraction that implements Semantica's `Ingestor` interface, fetching MCP resources and feeding them into processing pipelines—ideal for automated data pipelines rather than interactive graph manipulation.