MCP Integration
Connect any MCP-compatible agent to Nocturnus in 30 seconds. Use the context tool for fast working-set retrieval on every turn, then pair it with the HTTP Context API when you need goal-driven assembly and session diffs.
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 MCP using HTTP+SSE transport. The server reports its own protocol version string (e.g. 2025-11-25) during initialization -- this is the server's internal version identifier, not an official MCP specification version number.
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 16 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 | Unified context window — salience-ranked or goal-driven optimization | "Get the 50 most relevant facts" or "Get context for SLA eligibility" |
| 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?" |
| aggregate | COUNT/SUM/MIN/MAX/AVG over matched facts | "Count all active contracts" |
| bulk_assert | Write many facts in a single call | "Ingest a batch of extracted facts" |
| retract_pattern | Retract facts matching a wildcard pattern | "Delete all facts for a stale scope" |
| fork_scope / merge_scope / list_scopes / delete_scope | Git-like scope branching and merge workflows | "Fork a hypothesis scope, then merge if valid" |
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
The MCP context tool now supports the full unified context API. Use it for simple salience windows or goal-driven optimization directly from your MCP client:
Simple usage (salience-ranked)
{
"method": "tools/call",
"params": {
"name": "context",
"arguments": {
"maxFacts": 25,
"minSalience": 0.15,
"predicates": ["customer_tier", "sla_tier", "contract_value"],
"scope": "session_acme_42"
}
}
}Goal-driven usage (optimization engine)
{
"method": "tools/call",
"params": {
"name": "context",
"arguments": {
"maxFacts": 25,
"goals": [{"predicate":"eligible_for_sla","args":["acme_corp"]}],
"sessionId": "mcp-session-42",
"format": "natural",
"includeRules": true
}
}
}Adding goals, sessionId, format, or includeRules triggers the optimization engine. The MCP server also accepts the legacy alias minRelevance for minSalience.
| Context Task | Method | Where |
|---|---|---|
| Salience-ranked context | MCP context tool (simple args) | MCP |
| Goal-driven context | MCP context tool (with goals) | MCP |
| Incremental updates | HTTP POST /context/diff | Context API |
| Session cleanup | HTTP POST /context/session/clear | Context API |
Goal-driven context assembly now works directly through the MCP context tool. For incremental diffs and session cleanup, use the companion HTTP endpoints alongside MCP.
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.