Contraption MCP

Contraption Company MCP

An MCP (Model Context Protocol) server for Contraption Company essay, built on Chroma Cloud.

How to Install

Contraption Company MCP is available as a hosted MCP server with no authentication.

How to configure in common clients

Cursor

Use the deep link to install directly in Cursor: Install Contraption Company MCP.

Or, create or edit ~/.cursor/mcp.json:

{

"mcpServers": { "contraption-company": { "url": "https://mcp.contraption.co" } } }

ChatGPT

1. Open Settings → Connectors.
2. Click Create new connector.
3. Set MCP Server URL to https://mcp.contraption.co.
4. Leave authentication blank and save.

VS Code (Copilot Chat MCP)

Create or edit .vscode/mcp.json:

{

"servers": { "contraption-company": { "type": "http", "url": "https://mcp.contraption.co" } } }

Codex

Add to ~/.codex/config.toml:

[mcp_servers.contraption-company]

command = "npx" args = ["mcp-remote", "--transport", "http", "https://mcp.contraption.co"]

Claude Code

Run in your terminal:

claude mcp add --transport http contraption-company https://mcp.contraption.co

OpenAI SDK (Python)

from openai import OpenAI

client = OpenAI()

response = client.responses.create( model="gpt-5", input="List the newest Contraption Company blog posts.", tools=[ { "type": "mcp", "server_label": "contraption-company", "server_url": "https://mcp.contraption.co", "require_approval": "never", } ], ) print(response)

Features

• Search: Find posts and pages by query text
• Automatic Indexing: Syncs with the blog API on startup and via scheduled polling
• Full Content Access: Indexes all published posts and pages, including members-only content
• Fast Performance: Powered by FastAPI and Chroma Cloud
• Background Updates: Polls Ghost every few minutes for new, updated, or deleted posts and pages
• Query Logging: Records searches in a dedicated Chroma collection for analysis
• Docker Ready: Includes Dockerfile for easy deployment
• Well Tested: Comprehensive test suite with pytest

Run Locally

1. Clone and install:

git clone <repository>

cd mcp uv sync --all-extras

1. Configure environment:

cp .env.example .env

Edit .env with your credentials

1. Run the server:

./run.sh

Or: uv run python -m src.main

Docker

# Build

docker build -t contraption-mcp .

Run

docker run -p 8000:8000 --env-file .env contraption-mcp

Or use docker-compose

docker-compose up

Configuration

Running locally requires credentials for external services:

• Ghost Admin API Key: From your Ghost Admin panel (Settings > Integrations)
• Chroma Cloud Credentials: Tenant ID, Database, and API key from Chroma Cloud
• Chroma Query Collection (optional): Set CHROMA_QUERY_COLLECTION to override the default queries collection
• Voyage API Key: Required to generate contextualized embeddings
• Ghost Blog URL: Your Ghost blog's URL
• Polling Interval (optional): Set POLL_INTERVAL_SECONDS to override the default 5 minute sync cadence
• Members-only content and query logging are enabled by default. Ensure your privacy policy and access controls cover both.

Support and Privacy

• Support: hello@contraption.co
• Privacy policy: https://www.contraption.co/privacy/
• Query logging and members-only content are enabled, and the privacy policy must cover both.

MCP Tools

• fetch(id): Fetch a single post or page using the canonical URL as the identifier. Provide the id returned by list_posts/search (which is the canonical URL); slugs and shorthand schemes are also accepted but responses always resolve to full URLs.
• list_posts(sort_by, page, limit): List posts with pagination, returning canonical URLs as identifiers
• search(query, limit): Search posts and pages by query text; returns canonical URLs for result IDs

API Endpoints

• GET /: Server info (redirects to GitHub repo for non-MCP requests)
• GET /health: Health check
• GET /debug/search: Debug search endpoint (see /debug/docs for Swagger UI)
• /mcp/*: MCP protocol endpoints

Background Sync

The server polls the Ghost Admin API every 5 minutes to detect new, updated, or deleted posts and pages. Adjust the cadence by setting the POLL_INTERVAL_SECONDS environment variable.

Development

# Install dev dependencies

make dev

Run tests

make test

Lint and format

make format lint

Run all checks

make check

License

MIT