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

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 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
session.py	Provides a lazy singleton ContextGraph shared by all tools	mcp/session.py
schemas.py	Defines JSON‑Schema for type‑safe RPC payloads	mcp/schemas.py
tools/	Package containing 17 registered tools (extraction, decisions, graph, reasoning, export)	mcp/tools/
resources/registry.py	Maps semantica:// URIs to resource handlers	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.
4. Dispatcher resolves the tool name to an implementation in tools/.
5. Tool accesses the shared ContextGraph via get_graph() from 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:

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

{
  "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 before execution.

Recording a Decision

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

{
  "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, where record_decision executes:

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:

{
  "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 handles this:

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:

{
  "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
Decision Intelligence	record_decision, query_decisions, get_decision_provenance	mcp/tools/decisions.py
Graph Operations	add_entity, add_relation, search_graph, get_graph_summary, delete_node	mcp/tools/graph.py
Reasoning	forward_chain, abductive_reasoning	mcp/tools/reasoning.py
Export & Provenance	export_graph, get_provenance, export_decisions	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:

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 module implements a lazy singleton pattern for ContextGraph:

# 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.
• Shared state through 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. 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. 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.

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