Add MCP Integration

Add an MCP Integration

A catalog integration is a bundled local plugin whose only content is an mcp.json pointing at the vendor's remote server. The assistant ships it, the Integrations page lists it, and connecting it runs the MCP OAuth flow in assistant/src/mcp/mcp-oauth-provider.ts.

Scope: remote MCP servers in plugins/mcp-catalog/. For a full plugin that lives in another GitHub repo, see plugins/README.md § Marketplace.

Work in a worktree from origin/main. One provider per PR.

1. Research the server

From the vendor's MCP docs, record:

• The remote URL. Prefer streamable-http (docs often say "type": "http").
• The docs page URL. It is both homepage and documentationUrl.
• A one-line summary of what the tools do.

Reject a server that only runs locally (npx, uvx, Docker). The catalog ships no stdio servers.

2. Check OAuth support

The catalog's one-step connect needs the server to support OAuth discovery and dynamic client registration (DCR), because a plugin cannot ship a client secret.

URL=https://mcp.example.com/mcp
curl -sS -i -X POST "$URL" -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

Expect 401 with WWW-Authenticate: Bearer ... resource_metadata="<url>". Fetch that URL and take authorization_servers[0] as the issuer. Then fetch the issuer's metadata from the first URL that answers, in the order the MCP SDK tries them (buildDiscoveryUrls in @modelcontextprotocol/sdk client/auth.js):

Check the metadata the way the SDK does:

Do not judge token_endpoint_auth_methods_supported from the metadata. The registration in step 3 shows which method the server gives our public client.

Pick the setup mode:

• The rules hold and step 3 succeeds: oauth. The normal case.
• DCR works, but the vendor must allowlist our redirect URI first: manual. ramp is the example. Its setup.instructions tell the user what to ask the vendor for.
• No registration_endpoint, or step 3 only returns a confidential client (a client_secret and a client_secret_* auth method): not a catalog addition. It needs a pre-registered client, which the MCP OAuth flow does not support. Stop and report this.

Also check whether the vendor already has a main OAuth provider in assistant/src/oauth/seed-providers.ts. If it does, set integration.oauthProvider so the Integrations page groups both connections (see calendly, linear, notion, todoist).

3. Test registration

Register a throwaway client with the same shape as McpOAuthProvider.clientMetadata:

curl -sS -X POST <registration_endpoint> -H 'content-type: application/json' \
  -d '{"client_name":"Vellum Assistant (registration probe)","redirect_uris":["https://example.com/webhooks/oauth/callback"],"token_endpoint_auth_method":"none","grant_types":["authorization_code","refresh_token"],"response_types":["code"],"logo_uri":"https://www.vellum.ai/favicon.ico","software_version":"0.0.0"}'

A client_id with token_endpoint_auth_method: "none" in the response means the server registers public clients.

This probe does not prove the vendor accepts our real redirect URI. Each assistant resolves its own callback (resolveOauthCallbackUrl in assistant/src/inbound/oauth-callback-url.ts), and a vendor can restrict redirect hosts. If you know the callback URL of the assistant you will test with, register that instead of example.com. If the example.com probe is rejected for its redirect URI, retry with a real callback before you reject the server. Step 9 is the real test of the redirect.

4. Icon

Write plugins/mcp-catalog/<name>/icon.png: a PNG, 128x128, on an opaque white background so it reads on the dark theme. The inventory test requires at least 64x64.

Source, in order of preference:

1. The vendor's official asset (apple touch icon, a large favicon, a press kit).
2. Simple Icons, pinned to a commit URL, rasterized in the brand color.

magick <source> -resize 128x128 -background white -alpha remove -alpha off -strip PNG24:plugins/mcp-catalog/<name>/icon.png

Look at the result with the Read tool before you continue.

Write ICON_ATTRIBUTION.md beside it in the same form as the others: source link, what was done to it, and "It is a trademark of <Vendor> and is used only to identify this integration." circleback, craft, and wix show the official-asset form. atlassian shows the Simple Icons form.