diff --git a/modelcontextprotocol/README.md b/modelcontextprotocol/README.md index ab4f255a19d43..f2267db1ccad8 100644 --- a/modelcontextprotocol/README.md +++ b/modelcontextprotocol/README.md @@ -1,14 +1,18 @@ # Pipedream MCP Server -This is a reference implementation of the Pipedream MCP server. +This is a reference implementation of the Pipedream MCP server. You can run **your own MCP server** for [over 2,500 apps and APIs](https://pipedream.com/apps) and is powered by [Pipedream Connect](https://pipedream.com/docs/connect/). -You can run this server yourself or use the hosted version at mcp.pipedream.com and chat.pipedream.com. -You can also directly integrate with [Pipedream Connect](https://pipedream.com/docs/connect/) to get -access to all the integrations. +You can: + +- [Run the servers locally](#running-the-server-via-npx) with `npx @pipedream/mcp` +- [Host the servers yourself](#hosting-your-own-server) to use them within your app or company + +See the server in action at [mcp.pipedream.com](https://mcp.pipedream.com) and [chat.pipedream.com](https://chat.pipedream.com) We published this code as a reference, so you can better understand how to use Pipedream Connect for such an application. This is still a work in progress, and not fully documented. Please reach out to us if you have any questions. + ## ⭐ Features - Run **your own MCP server** for [over 2,500 apps and APIs](https://pipedream.com/apps) @@ -23,23 +27,40 @@ Pipedream's MCP servers use the [Pipedream Connect API](https://pipedream.com/do 1. [Sign up for Pipedream](https://pipedream.com/auth/signup) 2. [Create a project](https://pipedream.com/docs/workflows/projects/#creating-projects). Any accounts connected via MCP will be stored here. 3. [Create a Pipedream OAuth client](https://pipedream.com/docs/rest-api/auth/#creating-an-oauth-client) -4. Set the environment variables (See `.env.example`) (directly in your shell session, dot files, etc.) +4. Set the environment variables (See `.env.example`) (directly in your shell session, dot files, etc.): + +```bash +PIPEDREAM_CLIENT_ID=your_client_id +PIPEDREAM_CLIENT_SECRET=your_client_secret +PIPEDREAM_PROJECT_ID=your_project_id +PIPEDREAM_PROJECT_ENVIRONMENT=development +``` + +### Pipedream concepts to understand + +If you're running MCP servers for your app, you'll likely want to use the [SSE interface](#sse). The SSE server accepts two route params: -There are two ways to use this MCP server. +1. `external_user_id` — This is your user’s ID, in your system — whatever you use to uniquely identify them. Any requests made to that route are coupled to that end user, and would use the auth Pipedream stores for that user. [See the docs](https://pipedream.com/docs/connect/api/#external-users) for more detail. +2. `app` — The app's "name slug" (the unique identifier for the app), found in the **Authentication** section of [any Pipedream app](https://pipedream.com/apps). For example, the app slug for [Slack](https://pipedream.com/apps/slack) is `slack`. + +If your user `123` wants to connect to the `slack` MCP server, your MCP client would make a request to the `/123/slack` route. [See the SSE docs below](#sse) for more detail. + +## Server overview + +There are two ways to use this MCP server. 1 - App specific - `/{uid}/{app}` - This is currently available at [mcp.pipedream.com](mcp.pipedream.com). You can use an endpoint for each app. - All the tools available for that app will be available at that endpoint. +`/{external_user_id}/{app}` +This is currently available at [mcp.pipedream.com](mcp.pipedream.com). You can use an endpoint for each app. +All the tools available for that app will be available at that endpoint. 2 - Dynamic - `/{uid}` - This is a more experimental version, since it relies on tools being able to update dynamically. - We use this server to power the tools on [chat.pipedream.com](chat.pipedream.com). +`/{external_user_id}` +This is an experimental version, since it relies on tools being able to update dynamically. +We use this server to power the tools on [chat.pipedream.com](https://chat.pipedream.com). > [!NOTE] -> We made the code for the dynamic MCP server available in this repo. However you will not yet be able to run it locally. -> It relies on our internal Supabase instance. +> The code for the dynamic MCP server is available in this repo but you will not _yet_ be able to run it locally since it relies on an internal db. > > Please let us know if you'd like to run this yourself. @@ -56,7 +77,6 @@ If you have Docker installed locally, you can build and run the container: This exposes a generic MCP server at [http://localhost:3010/:external_user_id/:app](http://localhost:3010/:external_user_id/:app). - ## Development `cp .env.example .env` and fill in the details of your dev project. @@ -66,6 +86,7 @@ pnpm install ``` ### Start the server with Streamable HTTP Transport + ```bash pnpm dev:http ``` @@ -82,12 +103,12 @@ Then run the inspector: npx @modelcontextprotocol/inspector ``` -Use `http://localhost:3010/v1/{uuid}/{app}` for Streamable HTTP Transport or `http://localhost:3010/{uuid}/{app}` for SSE Transport. +Use `http://localhost:3010/v1/{external_user_id}/{app}` for Streamable HTTP Transport or `http://localhost:3010/{external_user_id}/{app}` for SSE Transport. These URLs can also be used by other clients (e.g. Cursor). - ### Stdio Transport setup + Stdio has only been tested with the MCP Inspector. ```bash @@ -100,7 +121,6 @@ Ensure the left side of the inspector matches this: ![Screenshot 2025-03-12 at 1 05 37 PM](https://github.com/user-attachments/assets/cc650999-353c-45da-add8-7d8de867d6ed) - Then press "List Tools" to fetch the list of MCP tools. ## License