Paragon MCP Server

Paragon MCP Server

What is Paragon MCP Server about?

Paragon MCP Server delivers a ready‑to‑run server that connects AI agents to the Paragon ActionKit catalog. It surfaces pre‑built actions for hundreds of SaaS integrations and supports custom OpenAPI‑defined actions, allowing agents to perform real‑world tasks on behalf of users.

How to use Paragon MCP Server?

1. Sign up for a Paragon account and obtain a project ID and JWT signing key.
2. Clone the repository and run npm install.
3. Copy .env.example to .env and fill in the required variables (PROJECT_ID, SIGNING_KEY or SIGNING_KEY_PATH, etc.).
4. Start the server with npm run start (or via the npx command shown below).
5. Configure your AI client (e.g., Cursor or Claude) to connect to the /sse endpoint, passing the user token in the Authorization header.

Key features of Paragon MCP Server

• Direct access to 130+ SaaS integrations via ActionKit.
• Automatic OAuth2 / API‑key flows through the Paragon Connect Portal.
• Optional custom actions by dropping OpenAPI specs into an openapi/ folder.
• Experimental proxy API tool that lets agents craft arbitrary API calls (with safety warnings).
• Simple SSE transport for low‑latency, streaming interactions.
• Environment‑driven limitation of integrations or tools via LIMIT_TO_INTEGRATIONS and LIMIT_TO_TOOLS.

Use cases of Paragon MCP Server

• Building AI assistants that schedule meetings, update CRM records, or post Slack notifications.
• Extending LLM‑powered agents with organization‑specific custom APIs without writing code.
• Rapid prototyping of conversational workflows that require secure OAuth authentication.
• Deploying a centralized integration layer for multiple AI products within an enterprise.

FAQ from the Paragon MCP Server

• What Node version is required?
  Node.js 22.14.0 (or newer) and npm.
• How are users authenticated?
  Clients send a Paragon User Token (RS256 JWT) in the Authorization: Bearer <token> header; the server verifies it with Paragon’s public key.
• Can I limit which integrations are exposed?
  Yes—set LIMIT_TO_INTEGRATIONS or LIMIT_TO_TOOLS in the .env file.
• Do I need to host a separate Connect Portal?
  No—the server references Paragon’s hosted Connect SDK; only the server URL is required.
• Is the proxy API tool safe?
  It is experimental; enable it with ENABLE_PROXY_API_TOOL=true and review generated requests before execution.
• How do I add custom actions?
  Enable ENABLE_CUSTOM_OPENAPI_ACTIONS=true and place OpenAPI spec files in the openapi/ directory following the naming conventions described in the README.

---

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)

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.