Axiom — MCP Blind Proxy Gateway

Axiom is a multi-tenant, SOC2-grade MCP gateway that lets AI agents safely talk to systems like Slack, Google, Square, and Sentry without ever seeing raw API tokens. It provides a Blind Proxy layer with a hardened token vault, FastMCP server, and observability so teams can build production agent workflows with strong guardrails.

• Multi-tenant: each tenant gets isolated credentials and audit trails.
• Blind Proxy: agents see only logical parameters (project, channel, customer) while Axiom injects OAuth tokens at runtime.
• SOC2-grade: designed for strict security, least-privilege, and compliance.
• First-class observability: agent traces, tool-call logs, and per-tenant metrics.

The core goal: “Let agents safely act on your real systems without ever handing them the keys.”

---

Engineer’s Overview

High-Level Architecture

At a high level, Axiom consists of three main Python packages under src/:

• auth/ — FastAPI app for OAuth flows and health:
  • GET /oauth/{provider}/start — redirect to Slack/Google/Square/Sentry for user consent.
  • GET /oauth/{provider}/callback — exchange authorization codes for tokens.
  • GET /healthz — liveness and readiness check for infra and dashboards.
• vault/ — encrypted token storage:
  • oauth_credentials SQLModel table (multi-tenant).
  • At-rest encryption with cryptography.Fernet keyed by AXIOM_VAULT_KEY.
  • Repository/service layer for upserting and reading OAuth token bundles.
• gateway/ — FastMCP server:
  • FastMCP("Axiom") instance with HTTP/SSE transport.
  • Custom GatewayAuthMiddleware that decodes a gateway JWT and writes an AuthContext into per-request state.
  • Adapters and tools for Sentry, and later Slack/Google/Square.

Data flow (simplified):

1. User hits /oauth/{provider}/start → redirected to provider consent.
2. Provider callback hits /oauth/{provider}/callback with code and state (tenant_id):
   • auth/app.py exchanges code for tokens via httpx.
   • Tokens are encrypted and stored in vault.oauth_credentials keyed by (tenant_id, provider).
3. Agent client connects to the FastMCP gateway (HTTP/SSE) with a gateway JWT:
   • GatewayAuthMiddleware decodes JWT → AuthContext(tenant_id, scopes, sub, …).
   • AuthContext is stored in FastMCP context state.
4. When an MCP tool runs (e.g. list_sentry_issues):
   • Dependency injection (Depends()) pulls the decrypted Sentry token out of the vault based on AuthContext.tenant_id.
   • Tool parameters visible to the LLM are only logical (e.g. org_slug, project_slug, environment, limit).
   • The adapter calls Sentry/Slack/etc with injected bearer tokens.

Agents never see or pass raw tokens; they only manipulate safe, typed parameters. All secrets stay server-side in the vault.

Key Components

• Config (src/core/config.py)

  • Central AppSettings via pydantic-settings, reading .env:
    • Core: AXIOM_ENV, DATABASE_URL, AXIOM_VAULT_KEY, AXIOM_JWT_SECRET, AXIOM_JWT_ALGORITHM.
    • Sentry: SENTRY_CLIENT_ID, SENTRY_CLIENT_SECRET, SENTRY_OAUTH_REDIRECT_URI, SENTRY_API_BASE_URL.
    • Slack/Google/Square: client IDs/secrets + redirect URIs and optional credentials paths.
  • Ensures one place to validate and manage env.

• AuthContext (src/core/types.py)

  • Pydantic v2 model with:
    • tenant_id: str
    • scopes: list[str]
    • sub: str | None
    • exp: datetime | None
    • raw_claims: dict[str, object]

• JWT Decoding (src/auth/jwt.py)

  • Uses python-jose to validate:
    • Signature via AXIOM_JWT_SECRET and AXIOM_JWT_ALGORITHM.
    • exp and required tenant_id / scopes claims.
  • Returns a strongly typed AuthContext.

• Vault (src/vault/)

  • models.py:
    • OAuthCredential SQLModel table: tenant_id, provider, access_token_enc, refresh_token_enc, expires_at, scopes, created_at, updated_at.
    • Unique constraint on (tenant_id, provider) for idempotent upserts.
  • crypto.py:
    • VaultCrypto uses cryptography.Fernet and AXIOM_VAULT_KEY.
    • encrypt_str/decrypt_str helpers for safe at-rest secrets.
  • db.py:
    • Async SQLAlchemy engine setup from DATABASE_URL (default sqlite+aiosqlite).
    • Async session factory and create_db_and_tables().
  • service.py:
    • store_oauth_tokens(...) to upsert encrypted access/refresh tokens & metadata.
    • get_oauth_tokens(...) returning a decrypted OAuthTokenBundle.

• Gateway Middleware & DI (src/gateway/)

  • middleware.py:
    • GatewayAuthMiddleware:
      • Reads Authorization: Bearer <gateway_jwt> from HTTP headers.
      • Decodes JWT via decode_gateway_jwt.
      • Persists AuthContext into FastMCP context state (auth_context key).
  • dependencies.py:
    • get_auth_context() pulls AuthContext back from context state.
    • require_scopes([...]) enforces logical scopes like "sentry:read".
    • get_db_session() yields an async SQLModel session.
    • get_sentry_token() looks up and decrypts the Sentry token for the current tenant.

• Control Plane API (src/auth/app.py)

  • Primary FastAPI entry point for Axiom (OAuth, Vault, control-plane endpoints).
  • Endpoints:
    • GET /healthz — basic health.
    • GET /oauth/{provider}/start?tenant_id=... — builds provider-specific URL with state=tenant.
    • GET /oauth/{provider}/callback?code=...&state=... — exchanges code → tokens, writes to vault.
  • Supports Sentry, Slack, Google, and Square via build_provider_registry().

First Blind Tool: list_sentry_issues

• Adapter (src/gateway/adapters/sentry.py)

  • SentryAdapter.list_issues(...):
    • Inputs: org_slug, project_slug, sentry_token, limit, optional environment.
    • Uses httpx.AsyncClient to call:
      • GET {SENTRY_API_BASE_URL}/projects/{org}/{project}/issues/.
    • Maps JSON fields into SentryIssueSummary Pydantic models.

• Schemas (src/gateway/schemas/sentry.py)

  • SentryIssueSummary: id, title, culprit, firstSeen, lastSeen, permalink, status, level.
  • ListSentryIssuesResult: issues: list[SentryIssueSummary], total: int.

• Tool Registration (src/gateway/tools/sentry_tools.py)

  • register_sentry_tools(mcp, sentry_adapter) defines:

    @mcp.tool(auth=require_scopes_auth("sentry:read"), exclude_args=["sentry_token"])
    async def list_sentry_issues(
        org_slug: str,
        project_slug: str,
        limit: int = 20,
        environment: str | None = None,
        sentry_token: str = Depends(get_sentry_token),
        ctx: Context | None = None,
    ) -> ListSentryIssuesResult:
        ...

  • Blind Proxy behavior:

    • sentry_token is injected via Depends(get_sentry_token) and hidden from tool schema via exclude_args.
    • LLM only sees and controls org_slug, project_slug, limit, environment.
    • Tool enforces "sentry:read" via FastMCP auth and require_scopes.

---

Running Axiom Locally

Prerequisites

• Python 3.11+
• uv installed locally (for env and dependency management).

Install Dependencies

From the repo root:

uv sync

This will create a virtual environment and install the dependencies defined in pyproject.toml.

Environment Setup

1. Copy the example env:

cp .env.example .env

2. Fill in:
   • AXIOM_VAULT_KEY — a 32-byte Fernet key (e.g., python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())").
   • AXIOM_JWT_SECRET — secret for validating gateway JWTs.
   • OAuth client IDs/secrets and redirect URIs for:
     • Sentry
     • Slack
     • Google
     • Square

Start the Server

Using uv (recommended):

uv run axiom-serve

Or directly with Python/uvicorn once dependencies are installed:

python -m uvicorn src.main:app --reload

This runs the Control Plane API (/healthz, /oauth/*, /debug/tool-calls). The MCP gateway at /mcp is no longer exposed; the Data Plane (e.g., Nexus) will be integrated in a later phase. The axiom-sse script is disabled until then.

Pricing Overview (Initial Draft)

These tiers reflect Axiom’s multi-tenant, SOC2-grade posture and the fact that infra, security/compliance, and downstream API/LLM calls are the primary cost drivers.

Tier 1 — Axiom Starter (Student / Hobby)

Positioning: free/very cheap, read-focused tier for experimentation and education.

• Price

  • $0/month for verified students and individual devs.

• Limits (per month, per tenant)

  • Up to 500 “tool-call credits” for non-critical / sandbox connectors (mocked SaaS, test Slack workspace, test DB).
  • Up to 5k agent traces and basic observability, similar to LangSmith’s free developer quota.
  • Limited concurrency: 1–2 active agents, single workspace, no SSO.

• Access policy

  • Read-only tools (list resources, preview actions, simulate changes) are unmetered as long as they don’t hit real external systems.
  • Write tools against production connectors are either:
    • Disabled, or
    • Consume from a small pool of 100–200 write credits/month.

• Compliance posture

  • Shared multi-tenant infra.
  • Standard SOC2 controls, but no custom DPAs, no dedicated support.

• Why this exists

  • Mirrors Vercel’s “free + small credit” model and LangSmith’s free tier.
  • Lets students/indies learn MCP + Blind Proxy patterns without exposing Axiom to unbounded cost or liability.

Tier 2 — Axiom Team (SMB / Startup)

Positioning: the main revenue tier for small teams running agentic workflows in production.

• Price (starting point)

  • $49–79/month per workspace (not per seat) + usage add-ons.
  • Includes 5,000–10,000 write tool-call credits / month.

• Metering

  • Each call to a “write” tool (Slack send, Square charge, Jira create, DB write, etc.) consumes 1–N credits depending on cost/risk.
  • Read tools (fetch data, simulate, validate) consume 0–0.25 credits; effectively cheap/free.
  • Additional credits: e.g. $10 per extra 10,000 write calls.

• Features

  • Multiple environments: dev / stage / prod, with environment-scoped credentials.
  • SOC2-aligned security, audit logs, per-tenant Vault isolation.
  • Role-based control over which tools can run in which environment.
  • Optional basic SSO (OAuth/OpenID) as an add-on.

• Hard guardrails

  • Soft cap on LLM tokens per month per workspace to avoid runaway cost.
  • Beyond cap, require:
    • BYO model key, or
    • Add-on LLM usage blocks.

• Why this works

  • Similar to Zapier’s “Professional/Team” (2k–50k tasks) and LangSmith’s trace-based pricing.
  • Using “per MCP tool call” as the atomic unit is:
    • Predictable (“we get 10k actions”),
    • Easier to map to business value,
    • Aligned with Axiom’s Blind Proxy architecture.

Tier 3 — Axiom Enterprise (Regulated / High Compliance)

Positioning: high-margin, compliance-heavy tier for banks, healthcare, and large SaaS.

• Price

  • Contract-based, starting around $25,000/year (similar to Vercel Enterprise entry points).
  • Usage bands and committed-action bundles on top.

• Metering

  • Negotiated per-action rate (e.g. per 1,000 tool calls) plus overage schedule.
  • Option for committed blocks (e.g. millions of calls at a discount).
  • Option: “unlimited internal tools, metered external connectors”.

• Features

  • Full SOC2 report access, DPAs/BAAs, data residency options.
  • Dedicated VPC or private link for the MCP gateway.
  • Fine-grained compliance controls:
    • Per-connector on-call approvals.
    • Just-in-time access for dangerous tools (payments, code deploys).
  • Custom SLAs, incident response commitments.
  • Multi-region disaster recovery and advanced audit export.

---

Axiom vs. Zapier (Mental Model)

Feature	Zapier Central	Axiom (Blind Proxy Gateway)
Logic	Rigid workflows (if-this-then-that)	Dynamic tool-use driven by LLMs and FastMCP tools
Security	Centralized / shared tokens	Blind Proxy; per-tenant vault; isolated credentials
Integration	8,000+ broad SaaS connectors	Deep, specialized adapters (Sentry, Square, etc.)
Cost	High per task / zap	Lower, gateway-centric subscription + tool-call metering
Target	Marketing / Ops / HR	Engineers, startups, and regulated product teams

You can think of Zapier as “no-code SaaS glue for humans,” while Axiom is “MCP-native, secure SaaS glue for agents,” with Blind Proxy semantics, token vaulting, and fine-grained control over what tools an LLM can call in which environment.