semantica/docs/reference/mcp_server.md

title, description, icon

title	description	icon
MCP Server	Model Context Protocol server — expose Semantica's full capability set to Claude Desktop, VS Code, Cursor, and any MCP-aware tool.	plug

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

Compatible with Claude Desktop, Windsurf, Cline, Continue, VS Code, Roo Code, Cursor, and any other MCP-aware tool.

---

Installation

pip install semantica

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

---

Configuration

Add Semantica to your MCP client's settings:

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

{
  "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"
      }
    }
  }
}

---

Environment Variables

Variable	Default	Description
SEMANTICA_KG_PATH	(none)	Path to a persisted graph to load on startup
SEMANTICA_LOG_LEVEL	WARNING	Log level: DEBUG, INFO, WARNING

---

Tools

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

Knowledge Extraction

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 },
    { "label": "Steve Jobs", "type": "PERSON", "start": 26, "end": 36 },
    { "label": "Cupertino",  "type": "LOCATION", "start": 40, "end": 49 },
    { "label": "1976",       "type": "DATE",     "start": 53, "end": 57 }
  ]
}

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." }
  ],
  "triplets": [
    { "subject": "Steve Jobs", "predicate": "founded", "object": "Apple Inc." }
  ]
}

Decision Intelligence

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"
}

Output:

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

Query recorded decisions by natural language, category, or retrieve all recent decisions.

Input:

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

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

Input:

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

Trace the causal chain upstream or downstream from a decision.

Input:

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

Graph Operations

Add a node/entity to the live knowledge graph.

Input:

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

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

Input:

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

Compute PageRank centrality and community detection over the current graph. Returns top nodes by influence and community count.

Return node count, decision count, and graph health status.

Reasoning & Export

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 the current knowledge graph.

Input:

{ "format": "json-ld" }

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

---

Resources

The MCP server also 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

---

Test Locally

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

# Or with Python
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

---

See Also

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