Skip to main content

​
Overview

The MCP Server exposes Athena’s core capabilities as standardized Model Context Protocol tools, making them consumable by any MCP-compatible client including Antigravity, Claude Desktop, Cursor, and other agentic IDEs.

​
Quick Start

​
stdio Transport (IDE Integration)

For local IDE integration using standard input/output: 
python -m athena.mcp_server

​
SSE Transport (Remote Access)

For remote or multi-client access using Server-Sent Events: 
python -m athena.mcp_server --sse --port 8765

​
IDE Configuration

Add Athena to your IDE’s MCP settings (e.g., .agent/mcp_config.json): 
{
  "mcpServers": {
    "athena": {
      "command": "python",
      "args": ["-m", "athena.mcp_server"],
      "cwd": "/path/to/your/athena/workspace"
    }
  }
}

​
Available Tools

The MCP server exposes 8 tools, each gated by the Permissioning Layer:
ToolPermissionSensitivityDescription
smart_searchreadinternalHybrid RAG search with RRF fusion
quicksavewriteinternalSave timestamped checkpoint to session log
health_checkreadpublicAudit Vector API and Database subsystems
recall_sessionreadinternalRetrieve recent session log content
governance_statusreadinternalCheck Triple-Lock compliance state
list_memory_pathsreadpublicList active memory directories
set_secret_modeadmin—Toggle demo/external mode
permission_statusread—Show permission state and tool manifest
Hybrid RAG search combining Canonical Memory, Tags, Vectors, GraphRAG, and filenames: 
result = smart_search(
    query="trading risk protocols",
    limit=10,
    strict=False,  # Filter low-confidence results
    rerank=False   # Apply LLM-based reranking
)
Returns: 
{
  "results": [...],
  "meta": {
    "query": "trading risk protocols",
    "limit": 10,
    "timestamp": "2026-03-03T10:30:00"
  }
}

​
quicksave

Save a checkpoint to the current session log: 
quicksave(
    summary="Implemented MCP server integration",
    bullets=[
        "Added 8 MCP tools with permission gates",
        "Configured stdio and SSE transports",
        "Integrated Triple-Lock governance"
    ]
)
The quicksave tool automatically checks Triple-Lock compliance and includes governance status in the response.

​
health_check

Run a health audit of core services: 
status = health_check()
# Returns: {"vector_api": {...}, "database": {...}, "overall": "PASS"}

​
Resources

The server exposes 2 resources accessible via URI:
URIDescription
athena://session/currentFull content of active session log
athena://memory/canonicalCanonical Memory (CANONICAL.md)

​
Permissioning Layer

All tools are gated by the Permission Engine (see Security for details).

​
Capability Tokens

4 escalating permission levels:
LevelAccessExample Tools
readQuery/read datasmart_search, recall_session
writeModify session logsquicksave
adminModify config, toggle modesset_secret_mode
dangerousDelete data (future, unused)—
Default caller level: write (can access read + write tools)

​
Sensitivity Labels

3 data classification tiers:
LabelDescriptionExamples
publicSafe for demos, external sharingHealth check, memory paths
internalNormal operational dataSession logs, search results
secretCredentials, finances, PIIAPI keys, trading data

​
Secret Mode

Toggle with set_secret_mode(True) when:
  • Screen sharing during demos
  • External pair-programming
  • Client presentations
When active:
  • ✅ health_check and list_memory_paths remain accessible (PUBLIC)
  • 🔒 All INTERNAL/SECRET tools are blocked
  • 📝 Remaining data sources auto-redact sensitive content ([REDACTED])
set_secret_mode(True)
# Returns: {"secret_mode": true, "blocked_tools": [...]}
Secret mode does not disable tools—it blocks access to INTERNAL/SECRET classified tools and redacts sensitive patterns from PUBLIC tool responses.

​
Architecture

The MCP server acts as a thin transport layer, exposing Athena SDK capabilities through the standardized MCP protocol while enforcing security policies via the Permission Gate.

​
Implementation Reference

See src/athena/mcp_server.py:58 for the smart_search tool implementation and src/athena/core/permissions.py for the permission gating logic.

​
Dependencies

pip install fastmcp>=2.0.0
The MCP server is included when you install Athena from source with pip install -e .

​
Next Steps

Security Model

Learn about permissioning, secret mode, and data residency

Vector RAG

Understand the hybrid search architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us