How it fits together
MCP hosts connect over stdio or HTTP. The server uses a shared async Postgres pool; public rows come from published public revisions, and scoped MCP API keys unlock in-tenant private published content according to key scope.
Visibility & keys
Anonymous callers see the public catalog. Bearer tokens (HTTP) or metadata secrets (stdio) map to MCP API keys with tenant/project scope stored hashed in the database.
Full-text & semantic search
Keyword search uses Postgres full-text ranking. Semantic search uses pgvector where embeddings are backfilled, with an OpenAI-compatible embedding endpoint configured on the server.
Spec-shaped tools
Pull whole OpenAPI documents or drill into operations and components — designed for agents that need structured fragments, not a wall of YAML.
Transports
stdio
Local MCP hosts (Claude Desktop, MCP Inspector, Cursor). Credentials can travel in tool call metadata when the host supports it.
Streamable HTTP
Remote endpoint at /mcp with Bearer tokens per request. Binds with OBJECTIFIED_MCP_HTTP_HOST / PORT (or CLI flags). Health at GET /health.
Tools exposed to hosts
Names follow the spec.* and project.* conventions from the server implementation.
Catalog & discovery
- ping — service id, version, Postgres reachability
- spec.list — cursor-paginated published specs (public catalog; optional private scope with API key)
- project.list — distinct projects visible to the caller
- spec.list_my_specs — same shape as spec.list; requires MCP API key
- spec.describe — metadata for one revision UUID
- spec.list_tags — public tags with counts
Search & retrieval
- spec.search — full-text search over public specs (ranked, paginated)
- spec.search_semantic — vector similarity when embeddings are configured (OpenAI-compatible endpoint)
- spec.get_openapi — full OpenAPI JSON for a revision
- spec.export_yaml — same bundle as YAML text
Operations & components
- spec.list_operations — compact index of paths and methods
- spec.describe_operation — parameters, body, responses, security
- spec.list_components — component keys by kind
- spec.describe_component — single component with $ref expansion
Authentication
- HTTP: send
Authorization: Bearer …. Missing or non-Bearer requests run as anonymous where allowed. - stdio: hosts may pass secrets via tool-call metadata fields documented for MCP auth (for example authorization or api_key shaped fields).
- Keys are scoped with JSON tenant/project UUID lists; the server intersects scope with revision visibility before returning private documents.
Run it yourself
The MCP package ships in this monorepo as objectified-mcp. Configure OBJECTIFIED_MCP_DATABASE_URL, OBJECTIFIED_MCP_INTERNAL_SECRET, and optional embedding variables, then start objectified-mcp serve --transport stdio|http. Full env reference lives in the package CONFIGURATION doc.
Docker Compose at the repo root can bring up Postgres, migrations, and the MCP image for local integration testing.