How to Integrate Semantica AGI with Other Systems: MCP, REST, and Agent Frameworks

You can integrate Semantica AGI via its Model-Context Protocol (MCP) server for native agent interoperability, through a REST API wrapper for HTTP clients, or using first-class adapters for frameworks like Agno and OpenClaw.

The semantica-agi/semantica repository exposes a universal integration surface built around a Model-Context Protocol (MCP) server architecture. Whether you are connecting external AI agents or embedding semantic pipelines into existing microservices, Semantica AGI offers three distinct integration paths that expose 12 core knowledge graph tools ranging from entity extraction to causal reasoning.

Understanding the Dual Integration Model

Semantica AGI supports two primary integration modes that wrap the same underlying pipelines. The MCP (Model-Context Protocol) approach is recommended for agent frameworks that natively understand MCP, while the REST API suits legacy systems requiring conventional HTTP/JSON endpoints. Both modes access identical functionality defined in semantica/mcp/server.py and semantica/server.py.

Method 1: MCP Integration with OpenClaw

For agents that speak MCP, Semantica generates a configuration snippet that instructs the agent gateway how to launch the Semantica MCP server and forward tool calls over stdio or sse transport.

Generating the MCP Configuration

The OpenClawMCPConfig class in integrations/openclaw/mcp_tool.py (lines 27-78) produces the JSON entry required by OpenClaw's mcporter.json:

from integrations.openclaw import OpenClawMCPConfig

# Generate the configuration snippet

config = OpenClawMCPConfig()
print(config.to_json())

Starting the Server and Wiring

First, start the MCP server:

python -m semantica.mcp_server

Then paste the JSON output into ~/.openclaw/mcporter.json and restart the gateway:

openclaw gateway restart

Once restarted, all 12 Semantica tools become native OpenClaw tools accessible to any running agent.

Method 2: REST API Integration Using OpenClawKGTool

When MCP is unavailable, use the OpenClawKGTool class (lines 86-254 in integrations/openclaw/mcp_tool.py) to call the REST API running at http://localhost:8000.

from integrations.openclaw import OpenClawKGTool

# Connect to the Semantica REST server

kg = OpenClawKGTool(base_url="http://localhost:8000")

# Extract entities and relationships

result = kg.extract("Alice visited the Eiffel Tower in Paris.")
print(result)  # Returns {'entities': [...], 'relations': [...]}

# Add custom entities

kg.add_entity(label="Mars", entity_type="Planet")

# Query and export

search_results = kg.query_graph("planet")
jsonld_export = kg.export_graph(fmt="json-ld")

Method 3: Agno Framework Integration

Semantica ships first-class Agno adapters that map core pipelines onto Agno's Toolkit and MemoryDb abstractions. Install via pip install semantica[agno].

Knowledge Graph Toolkit

The AgnoKGToolkit class in integrations/agno/kg_toolkit.py (lines 55-464) exposes graph-centric tools as native Agno capabilities:

from integrations.agno import AgnoKGToolkit
from agno.agent import Agent

# Initialize the toolkit

kg_toolkit = AgnoKGToolkit()

# Attach to an Agno agent

agent = Agent(tools=[kg_toolkit], show_tool_calls=True)

# The agent can now invoke Semantica functions natively:

# await agent.run_tool("extract_entities", {"text": "Bob lives in Berlin."})

Additional Agno Adapters

• AgnoContextStore: Graph-backed memory store implementing MemoryDb (integrations/agno/context_store.py)
• AgnoKnowledgeGraph: Multi-hop GraphRAG support (integrations/agno/knowledge_graph.py)
• AgnoDecisionKit: Decision-intelligence tools as a Toolkit (integrations/agno/decision_kit.py)
• AgnoSharedContext: Team-level shared ContextGraph with per-agent scoping (integrations/agno/shared_context.py)

These classes gracefully degrade when Agno is not installed, remaining importable but raising errors if passed to an Agno Agent.

Direct Pipeline Access (No External Agent)

For pure Python integration without an agent framework, instantiate the PipelineBuilder directly from semantica/pipeline/pipeline_builder.py:

from semantica.pipeline.pipeline_builder import PipelineBuilder

# Assemble parsers, extractors, reasoner, and graph

pipeline = PipelineBuilder().build()

# Execute full pipeline

result = pipeline.run("The quick brown fox jumps over the lazy dog.")

# Access the populated knowledge graph

graph = pipeline.context.graph
nodes = graph.find_nodes()

Core Architectural Components

Understanding these key files helps when customizing integrations:

• semantica/mcp/server.py: Core MCP server routing tool calls to internal pipelines.
• semantica/server.py: HTTP/REST gateway exposing the same tool surface.
• integrations/openclaw/mcp_tool.py: Implements OpenClawMCPConfig and OpenClawKGTool.
• integrations/agno/kg_toolkit.py: Provides AgnoKGToolkit for Agno agents.
• semantica/vector_store/registry.py: Pluggable backends including FAISS, Pinecone, Qdrant, and Weaviate.
• semantica/visualization/visualization_provenance.py: Optional audit trail for tool activity.

All components share a common configuration model (semantica/config.py) and logging utility (semantica/utils/logging.py), ensuring consistency across integration modes.

Summary

• MCP is the recommended path for modern agent frameworks, using OpenClawMCPConfig to generate gateway configuration files.
• REST API via OpenClawKGTool provides immediate HTTP access for systems that cannot run MCP clients.
• Agno integration offers native Toolkit and MemoryDb implementations through classes like AgnoKGToolkit and AgnoContextStore.
• Direct pipeline access via PipelineBuilder allows embedding Semantica AGI capabilities into any Python application without external dependencies.
• All 12 core tools (extraction, reasoning, export, etc.) are accessible through every integration path, unified by the server implementations in semantica/mcp/server.py.

Frequently Asked Questions

What transport protocols does the Semantica MCP server support?

The MCP server supports both stdio (standard input/output) and sse (Server-Sent Events) transports, configured via the mcporter.json entry generated by OpenClawMCPConfig in integrations/openclaw/mcp_tool.py.

Can I use Semantica AGI integration without installing Agno?

Yes. The Agno integration classes gracefully degrade when Agno is not present—they remain importable but cannot be instantiated as Agno agents. For non-Agno use cases, use the MCP server, REST API via OpenClawKGTool, or direct PipelineBuilder access.

Where is the REST API documentation or OpenAPI spec?

The REST endpoints are thin wrappers around the MCP tool surface defined in semantica/server.py. By default, the server runs on port 8000 (http://localhost:8000), and the OpenClawKGTool class demonstrates the available endpoints including extract, add_entity, query_graph, and export_graph.

How do I switch vector store backends when integrating?

Vector stores are configured through the registry in semantica/vector_store/registry.py, which supports FAISS, Pinecone, Qdrant, PGVector, Milvus, Weaviate, and SQLite. Specify your chosen backend in semantica/config.py before initializing the pipeline or server.

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