Custom MCP Connections

The Capsule MCP server lets AI assistants read and update your Capsule data on your behalf, using the Model Context Protocol (MCP). Connecting takes three steps: check your AI tool is supported, create an OAuth app in Capsule, then add the server to your AI tool.

Plan requirement: using the remote Capsule MCP server requires a subscription plan of Growth or above.

1. Check your AI tool is supported

Your AI tool (the "MCP client") must:

  • Support connecting to remote MCP servers over HTTP (not just local/stdio servers).
  • Support OAuth 2.1.
  • Let you enter your own client ID and client secret when adding the server (known as 'Pre-registration').

Not supported:

  • Personal access tokens / API keys. Authentication is OAuth only - you cannot use a Capsule API token to connect.
  • Clients that only support Dynamic Client Registration (DCR). If your AI tool expects to register itself automatically with Capsule and gives you nowhere to enter a client ID and secret, it can't connect.

2. Create an OAuth app

First, find the redirect URL (callback URL) for your AI tool in its documentation - many tools display it on the screen where you add an MCP server. This must match exactly: the most common cause of a failed connection is a mismatched redirect URL.

Then create the app:

  1. Go to register a new application. The Developer Hub requires a GitHub account to sign in and create OAuth applications.
  2. Fill in:
    • Name - what users will see on the Capsule authorisation screen, e.g. "Cursor".
    • Description - an optional description users will see on the Capsule authorisation screen.
    • URL - the homepage of your AI tool.
    • Redirect URL - the exact redirect/callback URL for your AI tool.
    • Contact email - a point of contact for us to use for you.
    • Application Type - Web Application.
  3. Save, then copy the client ID and client secret.

For more on OAuth 2 with Capsule, see Authentication.

3. Add the server to your AI tool

In your AI tool, add a custom or remote MCP server. For example, in Claude this is Settings → Connectors → Add custom connector. Refer to your AI tool's documentation for the exact steps. Use:

  • Name: Capsule (or your own custom name)
  • URL: https://mcp-server.capsulecrm.com/mcp
  • Client ID / Client secret: from step 2

Then click Connect. You'll be sent to Capsule to sign in and approve access. Once approved, the Capsule tools appear in your AI tool.

Notes

  • The connection acts as you. The assistant can only see and change what your own Capsule user account is allowed to see and change.
  • For a list of the tools currently available, see the Capsule MCP Tool Reference.
  • You can revoke access at any time by removing the custom MCP server from your AI tool, and by deleting the OAuth app from your applications.

Troubleshooting

Symptom Likely cause
Your AI tool never shows the Capsule sign-in screen The client ID or secret is missing or mistyped, or the redirect URL on your OAuth app doesn't exactly match the one your tool sent. Recheck your AI tool's documentation on adding custom MCP servers, including http/https and trailing characters.
Connects, but no tools appear Make sure your Capsule account is on the Growth, Advanced or Ultimate plan.
Other authentication errors See Authentication for errors relating to the OAuth protocol.
Token refresh errors OAuth access tokens expire after a set period. Most AI tools refresh the access token automatically. If yours doesn't and the connection stops working, disconnect and reconnect to Capsule.