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

> Learn to integrate Semantica AGI with MCP, REST API, and agent frameworks like Agno and OpenClaw. Unlock seamless interoperability for your AI systems.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-23

---

**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`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py) and [`semantica/server.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/integrations/openclaw/mcp_tool.py) (lines 27-78) produces the JSON entry required by OpenClaw's [`mcporter.json`](https://github.com/semantica-agi/semantica/blob/main/mcporter.json):

```python
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:

```bash
python -m semantica.mcp_server

```

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

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/integrations/openclaw/mcp_tool.py)) to call the REST API running at `http://localhost:8000`.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/integrations/agno/kg_toolkit.py) (lines 55-464) exposes graph-centric tools as native Agno capabilities:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/integrations/agno/context_store.py))
- **AgnoKnowledgeGraph**: Multi-hop GraphRAG support ([`integrations/agno/knowledge_graph.py`](https://github.com/semantica-agi/semantica/blob/main/integrations/agno/knowledge_graph.py))
- **AgnoDecisionKit**: Decision-intelligence tools as a `Toolkit` ([`integrations/agno/decision_kit.py`](https://github.com/semantica-agi/semantica/blob/main/integrations/agno/decision_kit.py))
- **AgnoSharedContext**: Team-level shared `ContextGraph` with per-agent scoping ([`integrations/agno/shared_context.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/pipeline/pipeline_builder.py):

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/server.py)**: Core MCP server routing tool calls to internal pipelines.
- **[`semantica/server.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/server.py)**: HTTP/REST gateway exposing the same tool surface.
- **[`integrations/openclaw/mcp_tool.py`](https://github.com/semantica-agi/semantica/blob/main/integrations/openclaw/mcp_tool.py)**: Implements `OpenClawMCPConfig` and `OpenClawKGTool`.
- **[`integrations/agno/kg_toolkit.py`](https://github.com/semantica-agi/semantica/blob/main/integrations/agno/kg_toolkit.py)**: Provides `AgnoKGToolkit` for Agno agents.
- **[`semantica/vector_store/registry.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/registry.py)**: Pluggable backends including FAISS, Pinecone, Qdrant, and Weaviate.
- **[`semantica/visualization/visualization_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/visualization/visualization_provenance.py)**: Optional audit trail for tool activity.

All components share a common configuration model ([`semantica/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/config.py)) and logging utility ([`semantica/utils/logging.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/mcporter.json) entry generated by `OpenClawMCPConfig` in [`integrations/openclaw/mcp_tool.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/registry.py), which supports FAISS, Pinecone, Qdrant, PGVector, Milvus, Weaviate, and SQLite. Specify your chosen backend in [`semantica/config.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/config.py) before initializing the pipeline or server.