MCP Server

semantica.mcp_server exposes Semantica’s knowledge graph, decision intelligence, semantic extraction, and reasoning capabilities as an MCP (Model Context Protocol) server over stdio:

12 MCP tools exposed: extract entities, query graph, record decisions, run reasoning, export results
No Python code required after launch: configure once, use from any MCP-aware client
Compatible with Claude Desktop, Windsurf, Cline, Continue, VS Code, Roo Code, Cursor

Server Interface

// Configure in your MCP client (Claude Desktop, Windsurf, Cursor, VS Code, etc.)
{
  "mcpServers": {
    "semantica": {
      "command": "semantica-mcp"
    }
  }
}

# Or run directly
semantica-mcp
# or
python -m semantica.mcp_server

semantica.mcp_server is a stdio server process, not a Python library. It exposes no importable classes: all interaction happens through MCP tool calls from a connected AI client.

The server communicates over stdio: don’t add logging to stdout. Any print() or logger output directed to stdout will corrupt the JSON-RPC message stream. All logging is written to stderr only. Configure log verbosity with the SEMANTICA_LOG_LEVEL environment variable.

What You Get

12 MCP Tools — Extract entities, extract relations, record decisions, query decisions, find precedents, trace causal chains, add entities, add relationships, run analytics, summarise graph, run reasoning, export graph.
3 Readable Resources — Live graph JSON (semantica://graph/summary), decision list, and schema/version info: readable by any MCP client.
Zero Infrastructure — Runs over stdio: no server, no port, no Docker required. One config block to activate in any MCP client.
Persistent Graphs — Point SEMANTICA_KG_PATH at a saved graph file to reload it automatically on every server startup.
Decision Intelligence — Record decisions, find precedents via hybrid similarity search, and trace causal chains across agent runs.
REST Alternative — The Explorer module offers a full HTTP API and browser dashboard if you prefer programmatic access.

Installation

pip install semantica

The MCP server is included in the base install: no extras required.

Configuration

Find your MCP client's settings file

Client	Settings file
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally
VS Code / Continue	`.vscode/mcp.json` or user settings
Windsurf / Cline / Roo Code	App-specific settings → MCP Servers

Add the Semantica MCP server config

{
  "mcpServers": {
    "semantica": {
      "command": "semantica-mcp"
    }
  }
}

{
  "mcpServers": {
    "semantica": {
      "command": "semantica-mcp",
      "env": {
        "SEMANTICA_KG_PATH": "/path/to/my_graph.json"
      }
    }
  }
}

{
  "mcpServers": {
    "semantica": {
      "command": "python",
      "args": ["-m", "semantica.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "semantica": {
      "command": "semantica-mcp",
      "env": {
        "SEMANTICA_KG_PATH": "/path/to/my_graph.json",
        "SEMANTICA_LOG_LEVEL": "INFO"
      }
    }
  }
}

Configure your MCP client’s command field exactly. The command field must point to the exact executable path (use which semantica-mcp on macOS/Linux to find it). A wrong path fails silently: the server just doesn’t appear in the tools list. Test with the raw echo | semantica-mcp command first to confirm the binary works.

Test locally before configuring your client

# Run the server directly (reads from stdin, writes to stdout)
semantica-mcp

# Or via Python module
python -m semantica.mcp_server

# Send a JSON-RPC initialize message to confirm it's working
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | semantica-mcp

Environment Variables

Variable	Default	Description
`SEMANTICA_KG_PATH`	(none: in-memory graph)	Path to a persisted graph file to load on startup
`SEMANTICA_LOG_LEVEL`	`WARNING`	Log verbosity: `DEBUG`, `INFO`, `WARNING`

The graph starts empty unless you set SEMANTICA_KG_PATH. The MCP server creates a fresh in-memory ContextGraph on first use. Set SEMANTICA_KG_PATH to a previously saved graph file to restore state across server restarts. Without it, all data is lost when the process exits.

Enable debug logging for troubleshooting. Set SEMANTICA_LOG_LEVEL=DEBUG in your MCP client’s env block, or run python -m semantica.mcp_server directly and inspect stderr output.

Tools

The MCP server exposes 12 tools that any connected AI assistant can call:

Tool	Category	Description
`extract_entities`	Extraction	NER: find people, places, organisations, concepts
`extract_relations`	Extraction	Typed relation and triplet extraction
`record_decision`	Decision Intelligence	Save a decision with reasoning and outcome
`query_decisions`	Decision Intelligence	Search recorded decisions by natural language or category
`find_precedents`	Decision Intelligence	Hybrid similarity search over past decisions
`get_causal_chain`	Decision Intelligence	Trace upstream / downstream causal chains
`add_entity`	Graph Operations	Add a node to the live graph
`add_relationship`	Graph Operations	Add a directed edge between two nodes
`get_graph_summary`	Graph Operations	Node count, decision count, graph status
`get_graph_analytics`	Graph Operations	PageRank centrality and community detection
`run_reasoning`	Reasoning	Forward-chain IF/THEN rules over facts
`export_graph`	Reasoning & Export	Serialise the graph (`turtle`/`ttl`: RDF Turtle aliases, `nt`, `xml`, `json-ld`, `json`)

Knowledge Extraction

extract_entities

Extract named entities (people, places, organisations, concepts) from text using Semantica NER.Input:

{ "text": "Apple Inc. was founded by Steve Jobs in Cupertino in 1976." }

Output:

{
  "entities": [
    { "label": "Apple Inc.", "type": "ORGANIZATION", "start": 0,  "end": 10,  "confidence": 0.98 },
    { "label": "Steve Jobs", "type": "PERSON",       "start": 26, "end": 36,  "confidence": 0.99 },
    { "label": "Cupertino",  "type": "LOCATION",     "start": 40, "end": 49,  "confidence": 0.97 },
    { "label": "1976",       "type": "DATE",          "start": 53, "end": 57,  "confidence": 0.95 }
  ],
  "count": 4
}

extract_relations

Extract typed relations and (subject, predicate, object) triplets from text.Input:

{ "text": "Steve Jobs founded Apple Inc. and led it until 2011." }

Output:

{
  "relations": [
    { "source": "Steve Jobs", "type": "founded", "target": "Apple Inc.", "confidence": 0.96 }
  ],
  "triplets": [
    { "subject": "Steve Jobs", "predicate": "founded", "object": "Apple Inc." }
  ],
  "relation_count": 1,
  "triplet_count": 1
}

Decision Intelligence

record_decision

Record a decision with full context, reasoning, and metadata into the knowledge graph.Input:

{
  "category": "model_selection",
  "scenario": "Choose LLM for production reasoning pipeline",
  "reasoning": "GPT-4 benchmark advantage justifies 3x cost increase",
  "outcome": "selected_gpt4",
  "confidence": 0.91,
  "decision_maker": "product_team",
  "valid_from": "2024-01-01",
  "valid_until": "2024-12-31"
}

Required fields: category, scenario, reasoning, outcome, confidence. Optional: decision_maker (defaults to "mcp_client"), valid_from, valid_until.Output:

{ "decision_id": "dec_a1b2c3", "status": "recorded" }

query_decisions

Query recorded decisions by natural language or category filter.Input:

{ "query": "model selection", "category": "model_selection", "limit": 5 }

All fields are optional. limit defaults to 10. When query is provided, similarity search is used. When omitted, category filter applies.

find_precedents

Find past decisions similar to a given scenario using hybrid similarity search.Input:

{ "scenario": "Choose cloud provider for HIPAA workload", "max_results": 5 }

max_results defaults to 5, maximum 50.

Use find_precedents before high-stakes decisions. The tool performs hybrid similarity search across all recorded decisions. Call it at the start of any significant decision path: it surfaces past reasoning that may be directly applicable, reducing redundant work and improving consistency across agent runs.

get_causal_chain

Trace the causal chain upstream or downstream from a decision.Input:

{ "decision_id": "dec_a1b2c3", "direction": "downstream", "max_depth": 5 }

direction accepts "upstream" or "downstream" (default: "downstream"). max_depth defaults to 5, maximum 20.

Graph Operations

add_entity

Add a node/entity to the live knowledge graph.Input:

{
  "id": "apple_inc",
  "label": "Apple Inc.",
  "type": "Organization",
  "metadata": { "founded": 1976, "hq": "Cupertino" }
}

Only id is required. label defaults to the id value. type defaults to "Entity".

add_relationship

Add a directed relationship (edge) between two existing entities.Input:

{
  "source": "steve_jobs",
  "target": "apple_inc",
  "type": "FOUNDED",
  "metadata": { "year": 1976 }
}

source and target are required. type defaults to "RELATED_TO".

get_graph_summary

Return a high-level summary of the current knowledge graph.Output:

{
  "node_count": 42,
  "decision_count": 5,
  "graph_ready": true
}

Takes no input parameters.

get_graph_analytics

Compute PageRank centrality and community detection over the current graph. Returns top nodes by PageRank, community count, and overall node/edge counts.Takes no input parameters.

Reasoning

run_reasoning

Run forward-chaining IF/THEN rules over a set of facts to derive new facts.Input:

{
  "facts": ["Employee(John)", "Manager(John)"],
  "rules": ["IF Manager(?x) THEN HasAuthority(?x)"]
}

Output:

{ "derived_facts": ["HasAuthority(John)"] }

Export

export_graph

Export the current knowledge graph to a serialisation format.Input:

{ "format": "json-ld" }

Supported formats: turtle, ttl, nt, xml, json-ld, json. Default is json-ld.

Resources

The MCP server exposes three readable resources:

URI	Description
`semantica://graph/summary`	High-level graph statistics
`semantica://decisions/list`	All recorded decisions (up to 50)
`semantica://schema/info`	Server version and available tools

Context — The ContextGraph that the MCP server operates on.
Semantic Extract — NER and relation extraction powering the MCP tools.
Reasoning — Forward-chaining engine behind run_reasoning.
Agno Integration — Use Semantica inside Agno multi-agent teams.

Context & Intelligence

Storage

Data Pipeline

Quality & Provenance

Output

Utilities

Server Interface

What You Get

Installation

Configuration

Environment Variables

Tools

Knowledge Extraction

Decision Intelligence

Graph Operations

Reasoning

Export

Resources

​Server Interface

​What You Get

​Installation

​Configuration

​Environment Variables

​Tools

​Knowledge Extraction

​Decision Intelligence

​Graph Operations

​Reasoning

​Export

​Resources

Server Interface

What You Get

Installation

Configuration

Environment Variables

Tools

Knowledge Extraction

Decision Intelligence

Graph Operations

Reasoning

Export

Resources