<p align="center"> <a href="https://www.useparagon.com/" target="blank"><img src="https://raw.githubusercontent.com/useparagon/aws-on-prem/master/assets/paragon-logo-dark.png" width="150" alt="Paragon Logo" /></a> </p>

<p align="center"> <b> The embedded integration platform for developers. </b> </p>

---

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

Example Chat	Setup Link

• 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 /sse parameter accepts any user ID in the ?user= query parameter to automatically authorize as a specific user while testing locally.}

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/sse?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/sse?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)

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 /sse: Establishes SSE connection for MCP communication
• POST /messages: Handles MCP message processing
• GET /setup: Handles integration setup flow

Authorization

The GET /sse endpoint (base URL for the MCP using the SSE transport) accepts an Authorization header with a Paragon User Token as the Bearer token.

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.

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.