MCP Integration
Connect any MCP-compatible agent to Nocturnus in 30 seconds. Cut token costs by 97% with goal-driven context optimization.
What is MCP?
The Model Context Protocol (MCP) is an open standard that lets AI agents discover and use tools via a universal interface. Nocturnus implements the MCP 2025-11-25 specification using HTTP+SSE transport.
When an agent connects to Nocturnus via MCP, it automatically discovers tools for storing facts, querying knowledge, running logical inference, and managing memory — all without writing integration code.
Connect in 30 Seconds
Add this to your MCP client configuration:
Cursor
Add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"nocturnus": {
"url": "http://localhost:9300/mcp/sse"
}
}
}Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"nocturnus": {
"url": "http://localhost:9300/mcp/sse",
"transport": "sse"
}
}
}Windsurf / Any MCP Client
Use the SSE endpoint URL: http://localhost:9300/mcp/sse
{
"mcpServers": {
"nocturnus": {
"url": "http://localhost:9300/mcp/sse",
"transport": "sse"
}
}
}localhost:9300 with your server's URL. Add "headers": {"Authorization": "Bearer YOUR_KEY"} when auth is enabled — see Security & Auth.
MCP with Authentication
MCP respects the same three auth modes as the REST API. Configure your MCP client headers accordingly:
Disabled mode (default)
No auth headers needed — just the SSE URL.
Legacy mode (API_KEY env var set)
{
"mcpServers": {
"nocturnus": {
"url": "http://localhost:9300/mcp/sse",
"transport": "sse",
"headers": {
"X-API-Key": "your-shared-secret"
}
}
}
}Managed / RBAC mode (AUTH_ENABLED=true)
{
"mcpServers": {
"nocturnus": {
"url": "http://localhost:9300/mcp/sse",
"transport": "sse",
"headers": {
"Authorization": "Bearer nai_a1b2c3d4...",
"X-Database": "production",
"X-Tenant-ID": "acme_corp"
}
}
}
}INFERENCE permission — all roles (reader, writer, admin) have it by default. Note: MCP routes default X-Tenant-ID to "default" if not specified, unlike REST endpoints which require it explicitly.
Available MCP Tools
Once connected, your agent can use these tools automatically:
| Tool | Description | Example Use |
|---|---|---|
| tell | Store a fact in the knowledge base | "Remember that Alice manages the London office" |
| teach | Define a logical rule for automatic reasoning | "If someone manages any office, they are a manager" |
| ask | Query with multi-step inference (optionally with proof chains) | "Who are all the managers?" |
| forget | Retract a fact (cascading truth maintenance) | "Forget that Alice manages the London office" |
| recall | Temporal query — what was true at a specific time | "What was true about Alice last Tuesday?" |
| context | Salience-ranked context window for agent reasoning | "Get the 50 most relevant facts" |
| compress | Compress episodic patterns into semantic summaries | "Consolidate repeated patterns" |
| cleanup | Evict expired and low-relevance facts | "Clear stale session data" |
| predicates | Discover the KB schema (predicate names, arities, counts) | "What types of facts are stored?" |
SSE Streaming
Connect to GET /mcp/sse for real-time notifications when facts are asserted or retracted. The server pushes notifications/resources/updated events, so agents stay in sync with knowledge base changes.
# Test SSE connection
curl -N http://localhost:9300/mcp/sseContext Optimization via MCP
MCP-connected agents can use the Context Management Engine to optimize their token spend. Instead of querying all facts, specify goals and get only what's relevant:
// MCP tool call
{
"method": "tools/call",
"params": {
"name": "context",
"arguments": {
"goals": [{"predicate": "eligible_for_sla", "args": ["acme_corp"]}],
"maxFacts": 25
}
}
}
// Returns: 15 goal-relevant facts, ~820 tokens
// vs. 150K tokens from querying everythingThis is the difference between $2.25 and $0.01 per request when using GPT-4o or Claude at $15/M tokens.
Agent-to-Agent Discovery
Nocturnus serves an Agent2Agent Protocol discovery card at GET /.well-known/agent.json. Other agents can automatically discover and interact with your fact database without manual configuration.