From 5590207fc53a9b8ea61d7b219c9ef41afaa01d56 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Wed, 21 May 2025 11:26:14 -0700 Subject: [PATCH 1/4] Rev on hosted MCP docs --- docs-v2/pages/connect/mcp/_meta.tsx | 5 +- docs-v2/pages/connect/mcp/developers.mdx | 90 +++++++++++++++--------- docs-v2/pages/connect/mcp/openai.mdx | 4 +- pnpm-lock.yaml | 13 +++- 4 files changed, 72 insertions(+), 40 deletions(-) diff --git a/docs-v2/pages/connect/mcp/_meta.tsx b/docs-v2/pages/connect/mcp/_meta.tsx index c754a4ac7a17f..97d34c2fa659d 100644 --- a/docs-v2/pages/connect/mcp/_meta.tsx +++ b/docs-v2/pages/connect/mcp/_meta.tsx @@ -2,8 +2,5 @@ export default { "index": "Overview", "developers": "Developers", "users": "Consumers", - "openai": { - title: "OpenAI", - display: "hidden", - }, + "openai": "OpenAI", } as const diff --git a/docs-v2/pages/connect/mcp/developers.mdx b/docs-v2/pages/connect/mcp/developers.mdx index b6d600cabc0a4..29ac83392e283 100644 --- a/docs-v2/pages/connect/mcp/developers.mdx +++ b/docs-v2/pages/connect/mcp/developers.mdx @@ -38,7 +38,7 @@ For either option, you'll need: #### Set up your environment -Set the following environment variables: +Set the following environment variables : ```bash PIPEDREAM_CLIENT_ID=your_client_id @@ -47,6 +47,8 @@ PIPEDREAM_PROJECT_ID=your_project_id # proj_xxxxxxx PIPEDREAM_ENVIRONMENT=development # development | production ``` +Learn more about [environments in Pipedream Connect](/connect/managed-auth/environments). + ### Authentication #### Developer authentication @@ -79,6 +81,18 @@ Pipedream provides [{process.env.PUBLIC_APPS}+ APIs as MCP servers](https://mcp. ```javascript +import { createBackendClient } from "@pipedream/sdk/server"; + +// Initialize the Pipedream client with the SDK +const pd = createBackendClient({ + environment: PIPEDREAM_ENVIRONMENT, + credentials: { + clientId: PIPEDREAM_CLIENT_ID, + clientSecret: PIPEDREAM_CLIENT_SECRET, + }, + projectId: PIPEDREAM_PROJECT_ID +}); + // Get all available apps (paginated) const apps = await pd.getApps(); @@ -89,6 +103,18 @@ const apps = await pd.getApps(); ```javascript +import { createBackendClient } from "@pipedream/sdk/server"; + +// Initialize the Pipedream client with the SDK +const pd = createBackendClient({ + environment: PIPEDREAM_ENVIRONMENT, + credentials: { + clientId: PIPEDREAM_CLIENT_ID, + clientSecret: PIPEDREAM_CLIENT_SECRET, + }, + projectId: PIPEDREAM_PROJECT_ID +}); + // Search by app name const notionApps = await pd.getApps({ q: "notion" }); const gmailApps = await pd.getApps({ q: "gmail" }); @@ -100,13 +126,17 @@ const slackApps = await pd.getApps({ q: "slack" }); ### Use Pipedream's remote MCP server -Pipedream MCP server supports both SSE and streamable HTTP transport types, with no configuration required by the developer or MCP client. +The remote MCP server is in beta, and we're looking for feedback. During the beta, the API is subject to change. +#### Supported transport types + +Pipedream MCP server supports both SSE and streamable HTTP transport types, with no configuration required by the developer or MCP client. + #### Base URL ``` -https://mcp.pipedream.net +https://remote.mcp.pipedream.net ``` #### API Authentication @@ -161,42 +191,33 @@ Include these headers in every HTTP request: ### Self-host Pipedream's MCP server +Hosting the MCP server locally or in your app will expose these routes: + +- `GET /:external_user_id/:app` - App-specific connection endpoint +- `POST /:external_user_id/:app/messages` - App-specific message handler + #### Using the `Dockerfile` -If you have Docker installed locally, you can build and run the container from the [reference implementation](https://github.com/PipedreamHQ/pipedream/blob/master/modelcontextprotocol/Dockerfile): +You can build and run the container from the [reference implementation](https://github.com/PipedreamHQ/pipedream/blob/master/modelcontextprotocol/Dockerfile): ```console > docker build -t pipedream-connect . > docker run -d --name pd-mcp -p 3010:3010 --env-file .env pipedream-connect:latest ``` -This exposes a generic MCP server at [http://localhost:3010/:external_user_id/:app](http://localhost:3010/:external_user_id/:app). - -#### Start the server with Streamable HTTP Transport - -```bash -pnpm dev:http -``` - -You can use the optional env var `PD_SDK_DEBUG` to print out all the requests and responses going to the Connect API: - -```bash -PD_SDK_DEBUG=true pnpm dev:http -``` - -#### Start the server with SSE +#### Running the server using npx ```bash npx @pipedream/mcp sse ``` -This exposes routes at: -- `GET /:external_user_id/:app` - App-specific SSE connection endpoint -- `POST /:external_user_id/:app/messages` - App-specific message handler + +The current npx package only supports the `sse` transport type, `http` is coming soon. + -#### Customize for your needs +#### Running the server locally -You can also host and customize the MCP server for your specific requirements: +You can also run the server locally and even customize the MCP server for your specific requirements: ```bash # Clone the repo @@ -204,18 +225,23 @@ git clone https://github.com/PipedreamHQ/pipedream cd pipedream/modelcontextprotocol # Install dependencies -npm install +pnpm install -# Build -npm run build - -# Run the SSE server -npm run start:sse:prod +# Start the server +pnpm dev:http ``` See the [MCP server README](https://github.com/PipedreamHQ/pipedream/blob/master/modelcontextprotocol/README.md) for detailed instructions on customization options. -### Use the MCP inspector +#### Debugging + +You can use the optional env var `PD_SDK_DEBUG` to print out all the requests and responses going to the Connect API: + +```bash +PD_SDK_DEBUG=true pnpm dev:http +``` + +### Using the MCP inspector The [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector) can be helpful when debugging tool calls. @@ -228,7 +254,7 @@ Enter the server URL: If using Pipedream's remote server: ``` -https://mcp.pipedream.net/{external_user_id}/{app_slug} +https://remote.mcp.pipedream.net/{external_user_id}/{app_slug} ``` If running locally: diff --git a/docs-v2/pages/connect/mcp/openai.mdx b/docs-v2/pages/connect/mcp/openai.mdx index 0a6bcbb151ab5..60e4eb2cf276f 100644 --- a/docs-v2/pages/connect/mcp/openai.mdx +++ b/docs-v2/pages/connect/mcp/openai.mdx @@ -82,7 +82,7 @@ const response = await client.responses.create({ { type: 'mcp', server_label: 'Notion', - server_url: `https://mcp.pipedream.net/${externalUserId}/${appSlug}`, + server_url: `https://remote.mcp.pipedream.net/${externalUserId}/${appSlug}`, headers: { Authorization: `Bearer ${accessToken}`, "x-pd-project-id": PIPEDREAM_PROJECT_ID, @@ -129,7 +129,7 @@ curl -X POST https://api.openai.com/v1/chat/completions \ { "type": "mcp", "server_label": "Notion", - "server_url": "https://mcp.pipedream.net/abc-123/'$APP_SLUG'", + "server_url": "https://remote.mcp.pipedream.net/abc-123/'$APP_SLUG'", "headers": { "Authorization": "Bearer '"$ACCESS_TOKEN"'", "x-pd-project-id": "$PIPEDREAM_PROJECT_ID", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c9e553c9617cf..cc0665b4c390c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -8564,8 +8564,7 @@ importers: specifier: ^3.0.3 version: 3.0.3 - components/neetoform: - specifiers: {} + components/neetoform: {} components/neetoinvoice: dependencies: @@ -15447,6 +15446,14 @@ importers: specifier: ^6.0.0 version: 6.2.0 + modelcontextprotocol/node_modules2/@modelcontextprotocol/sdk/dist/cjs: {} + + modelcontextprotocol/node_modules2/@modelcontextprotocol/sdk/dist/esm: {} + + modelcontextprotocol/node_modules2/zod-to-json-schema/dist/cjs: {} + + modelcontextprotocol/node_modules2/zod-to-json-schema/dist/esm: {} + packages/ai: dependencies: '@pipedream/sdk': @@ -35830,6 +35837,8 @@ snapshots: '@putout/operator-filesystem': 5.0.0(putout@36.13.1(eslint@8.57.1)(typescript@5.6.3)) '@putout/operator-json': 2.2.0 putout: 36.13.1(eslint@8.57.1)(typescript@5.6.3) + transitivePeerDependencies: + - supports-color '@putout/operator-regexp@1.0.0(putout@36.13.1(eslint@8.57.1)(typescript@5.6.3))': dependencies: From 741976860a3d873778d21002cf77642d079cc596 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Wed, 21 May 2025 11:28:58 -0700 Subject: [PATCH 2/4] Update developers.mdx --- docs-v2/pages/connect/mcp/developers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-v2/pages/connect/mcp/developers.mdx b/docs-v2/pages/connect/mcp/developers.mdx index 29ac83392e283..3dc3e043fccc5 100644 --- a/docs-v2/pages/connect/mcp/developers.mdx +++ b/docs-v2/pages/connect/mcp/developers.mdx @@ -38,7 +38,7 @@ For either option, you'll need: #### Set up your environment -Set the following environment variables : +Set the following environment variables: ```bash PIPEDREAM_CLIENT_ID=your_client_id From e8e7723df404632f55d29c7292ca8ee9f6d7dc43 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Wed, 21 May 2025 11:31:05 -0700 Subject: [PATCH 3/4] Update pnpm-lock.yaml --- pnpm-lock.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8710a6fadf5c7..caa2527f3b43c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -6041,8 +6041,7 @@ importers: specifier: ^1.5.1 version: 1.6.6 - components/heyreach: - specifiers: {} + components/heyreach: {} components/heysummit: dependencies: From 51ee7bdefe99bbf3caaa9b5cd692915343aa40b5 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Wed, 21 May 2025 11:32:58 -0700 Subject: [PATCH 4/4] Update developers.mdx --- docs-v2/pages/connect/mcp/developers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-v2/pages/connect/mcp/developers.mdx b/docs-v2/pages/connect/mcp/developers.mdx index 3dc3e043fccc5..66c0199fa2bfc 100644 --- a/docs-v2/pages/connect/mcp/developers.mdx +++ b/docs-v2/pages/connect/mcp/developers.mdx @@ -131,7 +131,7 @@ The remote MCP server is in beta, and we're looking for feedback. During the bet #### Supported transport types -Pipedream MCP server supports both SSE and streamable HTTP transport types, with no configuration required by the developer or MCP client. +The Pipedream MCP server supports both SSE and streamable HTTP transport types, with no configuration required by the developer or MCP client. #### Base URL