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 MCP-aware client.

What You Get

• 12 MCP tools — extract entities, build graphs, run SPARQL, find paths, get recommendations, embed, cluster, and more
• 3 readable resources — live graph JSON, entity list, and relationship list
• Zero infrastructure — runs over stdio, no server or port needed
• Claude Desktop ready — one config block to add to claude_desktop_config.json
• REST alternative — the Explorer module offers a full HTTP API if you prefer

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

{
  "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 verbosity: 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 to a serialization format.

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

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.