Paragon MCP 服务器

The embedded integration platform for developers.

---

Paragon MCP Server

A server implementation for Model Context Protocol (MCP) that integrates with ActionKit, an API by Paragon that provides access to prebuilt actions for 130+ integrations to your users' SaaS applications.

Features

• Add user-facing integrations from your Paragon account as available capabilities to your agent, for example:
  • Google Calendar: Create or update events and get calendar availability on your user's behalf.
  • Salesforce: Query and manage records from your user's CRM.
  • Slack: Send notifications to your user's Slack workspace.
• Automatically prompt users to authorize integrations with the Connect Portal, a prebuilt component for secure OAuth 2.0 and API Key intake flows.
• Optionally: add Custom Actions or direct API access as available tools in the MCP.

Prerequisites

To start using the Paragon MCP Server, you will need to sign up and register for a Paragon account.

• Node.js @ 22.14.0
• npm package manager

Installation

1. Clone the repository
2. Install dependencies:

npm install

Environment Variables

Create a .env file in the root directory by running:

cp .env.example .env

Set up the environment variables as described below:

• Required:
  • PROJECT_ID: Your Paragon project ID)
  • SIGNING_KEY: Your JWT signing key (requiredif SIGNING_KEY_PATH is not set)
  • SIGNING_KEY_PATH: Path to your JWT signing key file (required if SIGNING_KEY is not set)
• Optional:
  • LIMIT_TO_INTEGRATIONS: Comma-separated list of integration names to limit the types of available tools.
  • LIMIT_TO_TOOLS: Comma-separated list of tool names to additionaly limit available tools if needed.
  • PORT: Server port (default: 3001)
  • MCP_SERVER_URL: The URL of your hosted MCP Server. This will be used to generate Setup Links when your users are prompted to install integrations. (default: http://localhost:3001)
  • CONNECT_SDK_CDN_URL: Paragon Connect SDK CDN URL (default: https://cdn.useparagon.com/latest/sdk/index.js)
  • ACTIONKIT_BASE_URL: Paragon ActionKit base URL (default: https://actionkit.useparagon.com)
  • ZEUS_BASE_URL: Paragon API base URL (default: https://zeus.useparagon.com)
  • PROXY_BASE_URL: Paragon Proxy API base URL (default: https://proxy.useparagon.com)
  • NODE_ENV: Node environment (default: development) _{Note: When NODE_ENV is set to development, the /mcp and /sse endpoints accept any user ID in the ?user= query parameter to automatically authorize as a specific user while testing locally.}
  • ENABLE_LEGACY_SSE: Set to false to remove the deprecated /sse and /messages endpoints (default: true)
  • MCP_ALLOWED_HOSTS: Additional comma-separated Host header values accepted by /mcp. The host from MCP_SERVER_URL is allowed automatically.
  • MCP_ALLOWED_ORIGINS: Additional comma-separated Origin header values accepted by /mcp. The origin from MCP_SERVER_URL is allowed automatically.
  • MCP_SESSION_IDLE_TIMEOUT_MS: Time in milliseconds before an inactive Streamable HTTP session is closed (default: 1800000)
  • MCP_MAX_SESSIONS: Maximum number of concurrent Streamable HTTP sessions per server instance (default: 1000)

Running the Server

Start the server using:

npm run start

The server will start on http://localhost:3001 by default.

Client Configuration

Note: Cursor's MCP implementation is a very new protocol and is still in active development. You might encounter unexpected issues. When making changes to the MCP server URL, a full client restart is recommended. For more information about current limitations, see the Cursor MCP documentation.

Cursor

To use this MCP server with Cursor, add the following to your Cursor configuration file at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcp-actionkit-dev": {
      "url": "http://localhost:3001/mcp?user=[user-id]"
    }
  }
}

Replace:

• http://localhost:3001 with your server's domain
• user-id with the ID for the Connected User to use with ActionKit (this parameter only available in development mode)

Claude

To use this MCP server with Claude, add the following to your Claude configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "actionkit": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3001/mcp?user=[user-id]"]
    }
  }
}

Replace:

• http://localhost:3001 with your server's domain
• user-id with the ID for the Connected User to use with ActionKit (this parameter only available in development mode)

For production clients, send the Paragon User Token as an Authorization: Bearer <token> header on every MCP request.

Legacy SSE clients

Existing clients can continue using GET /sse and POST /messages while ENABLE_LEGACY_SSE is true. To migrate, update the configured URL from /sse to /mcp and use a client that supports Streamable HTTP before disabling legacy SSE.

Deploying the MCP Server

The Paragon MCP server can be completely self-hosted. Deploy the MCP Server via Docker in any cloud hosting platform of your choice.

For testing, you can one-click deploy the server through Heroku.

API Endpoints

• GET, POST, and DELETE /mcp: Handles stateful Streamable HTTP communication
• GET /sse: Establishes a deprecated legacy SSE connection when ENABLE_LEGACY_SSE=true
• POST /messages: Handles deprecated legacy SSE messages when ENABLE_LEGACY_SSE=true
• GET /setup: Handles integration setup flow

Authorization

The /mcp endpoint accepts an Authorization header with a Paragon User Token as the Bearer token. Streamable HTTP clients must retain and send the same token used to initialize the session on every subsequent GET or POST request. If the token is rotated, initialize a new session. A client may terminate its old session with DELETE using a rotated, unexpired token for the same user. The legacy GET /sse endpoint also accepts this header when legacy SSE is enabled.

The Paragon User Token is an RS256-encoded JWT that is verified using the public key stored by Paragon. Your MCP client (e.g. your application server or the service running your AI agent) will sign the User Token using the matching private key generated in the Paragon dashboard, which only your server has access to.

This allows the MCP to validate the authenticity of the requesting user using the JWT signature and public key. Once authenticated, the MCP will associate the user ID encoded in the JWT with the active MCP session.

Streamable HTTP sessions are stored in memory and close when their initializing token expires or after 30 minutes of inactivity by default. Clients must initialize a new session after expiration or a server restart. Deployments with multiple server instances must use session affinity so requests bearing the same Mcp-Session-Id reach the instance that created it.

Adding Custom Actions with OpenAPI

To add your own Custom Action definitions:

1. Set ENABLE_CUSTOM_OPENAPI_ACTIONS=true in your environment (e.g. .env file).
2. Create an openapi/ subfolder at the root of the repository.
3. Add OpenAPI specs in YAML or JSON format, using the integration name as the file name.
   • For example, if you are adding Custom Actions for Google Calendar, the OpenAPI specs should be located at: openapi/googleCalendar.json.
   • If you are adding Actions for a Custom Integration, use the SDK name of the integration, with the custom. prefix: openapi/custom.spotify.json.

The MCP will automatically match OpenAPI files with Active integrations in your Paragon project to augment the list of available tools returned by the MCP.

Using experimental Proxy API tool

[!WARNING] Enabling this tool allows your agent to write its own API requests with the account you connect. Always review the request before allowing the agent to use this tool to safeguard against unexpected changes.

To allow the agent to write its own requests to the integration API, set ENABLE_PROXY_API_TOOL=true in your environment.

License

This project is open source and available under the MIT License.