Horizon Notes MCP

A small FastMCP notes server prepared for deployment on Prefect Horizon, with a production Supabase Postgres database managed by Pulumi.

Horizon owns the public deployment boundary: GitHub builds, TLS, OAuth, access control, scaling, preview environments, and request observability. The repository only owns the MCP tools and their application data.

MCP client -> Horizon OAuth gateway -> FastMCP server -> Supabase Postgres

The five tools create, list, read, update, and delete notes in one shared workspace. Horizon decides who can reach that workspace. The server deliberately does not trust undocumented identity headers or pretend that gateway users map to application-level note owners.

Deploy on Horizon

1. Push this repository to GitHub.

2. Sign in at horizon.prefect.io and connect the GitHub repository.

3. Create a server with these values:

   • Server name: horizon-notes or another available name

   • Entrypoint: server.py:mcp

   • Authentication: enabled

   • Environment variable: FASTMCP_STATELESS_HTTP=true

4. Provision Supabase by following infra/README.md, then add the secret Pulumi databaseUrl output to Horizon as DATABASE_URL.

5. Deploy the server. Horizon detects pyproject.toml, installs the Python dependencies, and publishes an endpoint such as https://horizon-notes.fastmcp.app/mcp.

6. Test every tool in Horizon Inspector or ChatMCP before connecting another client.

Every push to the configured production branch triggers a deployment. Pull requests receive preview deployments, so this branch can be pushed and opened as a PR before it is merged.

Related MCP server: Notebook MCP Server

Connect a client

Use the connection snippet produced by Horizon. For the included Claude Code plugin:

export SQLITE_NOTES_MCP_URL=https://your-server-name.fastmcp.app/mcp
claude plugin marketplace add "$PWD" --scope project
claude plugin install sqlite-notes@mcp-auth-local --scope project

Open /mcp, choose sqlite-notes, and complete the Horizon sign-in flow.

Run locally

Local HTTP mode intentionally has no authentication. It is for development on loopback only.

uv sync
uv run horizon-notes

The MCP endpoint is http://127.0.0.1:8000/mcp. Without DATABASE_URL, local development falls back to SQLite at MCP_DATABASE_PATH. Optional variables are documented in .env.example.

Verify the exact object Horizon imports:

uv run fastmcp inspect server.py:mcp

Test

uv run pytest

Environment variables

• DATABASE_URL: secret Supabase transaction-pooler URL used by the deployed MCP.

• FASTMCP_STATELESS_HTTP=true: enables stateless HTTP for Horizon autoscaling.

• MCP_DATABASE_PATH: optional SQLite path for local development only.

• MCP_HOST and MCP_PORT: optional local server bind settings.

Pulumi uses SUPABASE_ACCESS_TOKEN to provision the database. The infrastructure project uses an ignored local filesystem state backend, so it does not require a Pulumi account, Pulumi Cloud, or PULUMI_ACCESS_TOKEN. None of the provisioning credentials belong in Horizon. SUPABASE_URL, anon keys, and service-role keys are not needed because the service uses a direct Postgres connection.

Data boundary

Production notes live in the private horizon_notes Postgres schema, outside Supabase's default Data API schemas. The MCP creates the schema and table idempotently at startup. Local SQLite remains available only as a zero-configuration development fallback.

Horizon authentication protects the MCP endpoint. It does not by itself make rows private to each user, so this server correctly describes the notes as shared.