ScaleKit Exa MCP Security

Why this project exists

AI agents are most useful when they can reach current information, but passing a raw search API key into every desktop client creates unnecessary risk. This server keeps the Exa credential on trusted infrastructure and places an OAuth 2.1 boundary in front of the MCP transport.

The result is a clean separation of responsibilities:

• Exa finds, extracts, and ranks web content.

• ScaleKit handles OAuth discovery and validates bearer tokens.

• FastAPI hosts public service endpoints and the remote MCP transport.

• MCP gives Claude, Windsurf, Cursor, custom agents, and other compatible clients the same typed tool interface.

Related MCP server: m365-mcp-server

Highlights

Architecture

sequenceDiagram
    autonumber
    participant Client as MCP Client
    participant API as FastAPI / MCP
    participant SK as ScaleKit
    participant Exa as Exa API

    Client->>API: POST /exa without token
    API-->>Client: 401 + WWW-Authenticate metadata URL
    Client->>SK: OAuth 2.1 authorization + PKCE
    SK-->>Client: Scoped access token
    Client->>API: tools/call + Bearer token
    API->>API: Validate signature, issuer, audience, expiry, scope
    API->>Exa: Server-side x-api-key request
    Exa-->>API: Ranked results / content
    API-->>Client: Structured MCP tool result

Only /exa is protected. The landing page, health check, service information, and OAuth metadata remain public so browsers, deployment health checks, and MCP clients can discover the service.

Endpoints

Tool reference

exa_search

Search the live web and optionally enrich each result with extracted content.

exa_get_contents

Retrieve complete content for Exa result IDs or URLs.

exa_find_similar

Find pages that are semantically related to an absolute HTTP or HTTPS URL. It supports result count, domain filters, publication dates, content, highlights, summaries, and moderation.

{
  "success": true,
  "query": "recent MCP authorization research",
  "search_type": "auto",
  "resolved_search_type": "neural",
  "request_id": "req_01J...",
  "num_results": 1,
  "results": [
    {
      "title": "Example result",
      "url": "https://example.com/article",
      "id": "https://example.com/article",
      "publishedDate": "2026-06-01T12:00:00Z",
      "author": "Example Author",
      "text": "Extracted page content...",
      "highlights": ["A relevant passage..."],
      "summary": "A concise result summary..."
    }
  ],
  "cost_dollars": { "total": 0.007 }
}

Quickstart

Prerequisites

• Python 3.11–3.14

• uv for reproducible dependency management

• An Exa API key

• A ScaleKit account with an MCP protected resource

1. Clone and install

git clone https://github.com/tirth1263/ScaleKit-Exa-MCP-Security.git
cd ScaleKit-Exa-MCP-Security
uv sync --all-extras

2. Register the MCP resource in ScaleKit

1. Open ScaleKit Dashboard → MCP Servers → Add MCP Server.

2. For local development, register http://localhost:8000/exa as the server URL.

3. Add the exa:read scope.

4. Save the MCP server and copy its resource ID and protected-resource metadata JSON.

5. Copy the environment URL, client ID, and client secret from Settings → API credentials.

The token audience must exactly match SCALEKIT_AUDIENCE_NAME. When you deploy, update both values to the public HTTPS /exa URL.

3. Configure environment variables

cp .env.example .env

Populate the following values in .env:

EXA_API_KEY=your_exa_api_key
SCALEKIT_ENVIRONMENT_URL=https://your-environment.scalekit.com
SCALEKIT_CLIENT_ID=your_client_id
SCALEKIT_CLIENT_SECRET=your_client_secret
SCALEKIT_RESOURCE_ID=res_your_resource_id
SCALEKIT_AUDIENCE_NAME=http://localhost:8000/exa
SCALEKIT_REQUIRED_SCOPE=exa:read
PUBLIC_BASE_URL=http://localhost:8000
ALLOWED_HOSTS=localhost,127.0.0.1

You can also set METADATA_JSON_RESPONSE to the exact JSON copied from ScaleKit. That value takes precedence over metadata generated from the individual settings.

4. Run

uv run main.py

Open http://localhost:8000 for the website or check the service:

curl http://localhost:8000/health
curl -i http://localhost:8000/exa

The second request should return 401 Unauthorized with a WWW-Authenticate header when OAuth is configured.

Connect an MCP client

Remote clients can connect directly to https://your-host.example/exa. Clients that need a local stdio bridge can use mcp-remote:

{
  "mcpServers": {
    "secure-exa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-host.example/exa"
      ]
    }
  }
}

For protocol-level testing, start the MCP Inspector:

npx -y @modelcontextprotocol/inspector@latest

Then connect its Streamable HTTP transport to http://localhost:8000/exa and complete the ScaleKit authorization flow.

Development and verification

# Lint the full repository
uv run ruff check .

# Run unit and ASGI integration tests
uv run pytest

# Build the production container
docker build -t scalekit-exa-mcp-security .

# Run through Docker Compose
docker compose up --build

The test suite verifies Exa request shaping, sanitized upstream errors, public-route behavior, OAuth challenges, scope options, fail-closed configuration, security headers, and input validation.

Deployment

Docker

The included multi-stage Dockerfile runs as a non-root user, uses the pinned uv.lock, exposes a container health check, and honors the platform-provided PORT.

docker build -t scalekit-exa-mcp-security .
docker run --rm -p 8000:8000 --env-file .env scalekit-exa-mcp-security

Render blueprint

After forking the repository, use the included render.yaml:

Set every secret marked sync: false, then update:

PUBLIC_BASE_URL=https://your-service.onrender.com
SCALEKIT_AUDIENCE_NAME=https://your-service.onrender.com/exa
ALLOWED_HOSTS=your-service.onrender.com

Finally, update the MCP server URL in ScaleKit to the same public /exa address. OAuth will fail if the registered audience and deployed audience differ.

Public website

The same web/ experience served at the FastAPI root is published through the included GitHub Pages workflow:

https://tirth1263.github.io/ScaleKit-Exa-MCP-Security/

GitHub Pages hosts the public project website. A production MCP runtime must be deployed with the private Exa and ScaleKit environment variables; secrets are never added to the static site.

Security design

• Fail closed: /exa returns 503 rather than becoming public when ScaleKit server credentials are missing.

• Narrow authorization: the default policy requires the exa:read scope and the exact configured audience.

• No browser token storage: the website is documentation only and never asks for or stores access tokens.

• No client-side Exa credential: EXA_API_KEY is read exclusively by the backend.

• Sanitized errors: network details and secrets are not returned through tool results.

• Constrained browser surface: CORS is disabled unless an allowlist is supplied; credentials are never enabled with wildcard origins.

• Defensive headers: CSP, frame denial, MIME sniffing protection, referrer policy, and browser permission restrictions are added centrally.

• Non-root container: the final Docker image runs under an unprivileged app account.

Read SECURITY.md before operating the service publicly.

Project structure

.
├── src/scalekit_exa_mcp/
│   ├── auth.py          # ScaleKit bearer-token ASGI middleware
│   ├── config.py        # Environment configuration and RFC 9728 metadata
│   ├── exa_client.py    # Async Exa REST client
│   ├── main.py          # FastAPI app, public routes, and MCP mount
│   └── server.py        # exa_search, exa_get_contents, exa_find_similar
├── tests/               # Unit and ASGI integration tests
├── web/                 # Responsive website deployed to GitHub Pages
├── .github/workflows/   # CI and Pages deployment
├── Dockerfile           # Multi-stage, non-root production image
├── render.yaml          # One-click Render blueprint
├── pyproject.toml       # Pinned application and test dependencies
└── main.py              # `uv run main.py` entry point

Troubleshooting

Acknowledgements

This project is an original, production-focused implementation inspired by Arindam Majumder's ScaleKit + Exa MCP tutorial project and video walkthrough. It follows the current official guidance from ScaleKit MCP authentication, the Model Context Protocol, and the Exa API reference.

License

Released under the MIT License. Built by Tirth Rank.