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

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
Tool Registry	Aggregates tool definitions from all mcp/tools/* modules and exposes them via tools/list	semantica_mcp/mcp/tools/__init__.py
Graph Tools	Handles entity and relationship operations, search, analytics, and persistence	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
MCP Ingestor	Fetches resources from remote MCP servers and feeds them into Semantica pipelines	semantica/ingest/mcp_ingestor.py

Starting the MCP Server

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

python -m semantica_mcp.mcp

Alternatively, invoke the server module directly:

python -m semantica_mcp.mcp.server

The server initializes logging and logs its startup status:

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 provides the primary interface for Python applications. Instantiate it with either an HTTP endpoint or stdio transport:

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:

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

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

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:

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:

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:

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

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:

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:

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, 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.

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