Skip to content

Commit 77030e8

Browse files
dannyrooseveltdannyroosevelt
committed
Adding info for remote servers
1 parent 005a4c3 commit 77030e8

File tree

2 files changed

+187
-67
lines changed

2 files changed

+187
-67
lines changed

‎docs-v2/pages/connect/mcp/developers.mdx‎

Lines changed: 179 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,184 @@
1-
import { Steps } from 'nextra/components'
1+
import { Callout, Steps, Tabs } from 'nextra/components'
22

3-
# Deploy Pipedream MCP to your agent
4-
Deploy Pipedream's MCP servers to your application or agent and make authenticated request on behalf of your customers. Refer to our reference implementation [here](https://github.com/PipedreamHQ/pipedream/blob/master/modelcontextprotocol/README.md).
3+
# Add Pipedream MCP to your app or agent
54

6-
## Quickstart
5+
Add Pipedream's MCP server to your application or agent to make tool calls on behalf of your users to {process.env.PUBLIC_APPS}+ APIs and 10,000+ tools.
76

8-
<Steps>
7+
## Overview
98

10-
#### Prerequisites
9+
Pipedream's MCP server code is [publicly available in GitHub](https://github.com/PipedreamHQ/pipedream/blob/master/modelcontextprotocol/README.md), and you have two options for using Pipedream's MCP server in your app:
1110

12-
To run your own MCP server, you'll need:
11+
1. [Use Pipedream's remote MCP server](#use-pipedreams-remote-mcp-server)
12+
2. [Self-host Pipedream's MCP server](#self-host-pipedreams-mcp-server)
13+
14+
### Pipedream concepts to understand
15+
16+
The MCP server accepts two route params:
17+
18+
**`external_user_id`**
19+
20+
- This is your user’s ID, in your system: whatever you use to uniquely identify them
21+
- Any requests made to that route are coupled to that end user and uses the connected account tied to that user
22+
- [See here](/connect/api/#external-users) for more detail
23+
24+
**`app`**
25+
26+
- The app's "name slug" (the unique identifier for the app)
27+
- [See below](#discover-available-mcp-servers) for discovering available apps
28+
29+
### Account connections
30+
31+
One of the core features of Pipedream Connect and our MCP product is the ability for your users to easily connect their accounts without having to build any of the authorization flow or handle token storage.
32+
33+
You can handle account connections in one of two ways in your app:
34+
35+
### Add a button in your UI
36+
- Use Pipedream's [frontend SDK](/connect/managed-auth/quickstart/#use-the-pipedream-sdk-in-your-frontend) to let users connect their account directly in your UI
37+
- You can see an example of this when you connect any account in [mcp.pipedream.com](https://mcp.pipedream.com)
38+
39+
### Return a link
40+
- Use [Connect Link ](/connect/managed-auth/quickstart/#or-use-connect-link) to let your users open a Pipedream hosted page to connect their account
41+
- There is no implementation required for this option since it's already handled in Pipedream's MCP server
42+
- If a user doesn't have a connected account that's required for a given tool call, we'll return a URL in the tool call response. For example:
43+
44+
```
45+
https://pipedream.com/_static/connect.html?token=ctok_xxxxxxx&connectLink=true&app={appSlug}
46+
```
47+
48+
## Getting started
49+
50+
### Prerequisites
51+
52+
For either option, you'll need:
1353

1454
1. A [Pipedream account](https://pipedream.com/auth/signup)
1555
2. A [Pipedream project](/projects/#creating-projects). Accounts connected via MCP will be stored here.
1656
3. [Pipedream OAuth credentials](/rest-api/auth/#oauth)
1757

18-
#### Set up environment variables
58+
#### Set up your environment
1959

2060
Set the following environment variables:
2161

2262
```bash
2363
PIPEDREAM_CLIENT_ID=your_client_id
2464
PIPEDREAM_CLIENT_SECRET=your_client_secret
25-
PIPEDREAM_PROJECT_ID=your_project_id
26-
PIPEDREAM_ENVIRONMENT=development
65+
PIPEDREAM_PROJECT_ID=your_project_id # proj_xxxxxxx
66+
PIPEDREAM_ENVIRONMENT=development # development | production
67+
```
68+
69+
### Discover available MCP servers
70+
71+
Pipedream provides [{process.env.PUBLIC_APPS}+ APIs as MCP servers](https://mcp.pipedream.com). Each server corresponds to an app integration (like Notion, Gmail, or Slack) and has its own specific set of tools that you can expose to OpenAI.
72+
73+
<Tabs items={['List all apps', 'Search for a specific app']}>
74+
<Tabs.Tab>
75+
```javascript
76+
// Get all available apps (paginated)
77+
const apps = await pd.getApps();
78+
79+
// Each app has these key properties:
80+
// - name_slug: Used in the MCP server URL (e.g., "notion", "gmail", "slack")
81+
// - name: Display name (e.g., "Notion", "Gmail", "Slack")
82+
```
83+
</Tabs.Tab>
84+
<Tabs.Tab>
85+
```javascript
86+
// Search by app name
87+
const notionApps = await pd.getApps({ q: "notion" });
88+
const gmailApps = await pd.getApps({ q: "gmail" });
89+
const slackApps = await pd.getApps({ q: "slack" });
90+
```
91+
</Tabs.Tab>
92+
</Tabs>
93+
94+
### Use Pipedream's remote MCP server
95+
96+
<Callout type="info">
97+
Pipedream MCP server supports both SSE and streamable HTTP transport types, with no configuration required by the developer or MCP client.
98+
</Callout>
99+
100+
#### Base URL
101+
102+
```
103+
https://mcp.pipedream.net
104+
```
105+
106+
#### Authentication
107+
108+
To authenticate requests to Pipedream's MCP server, you need to include an access token with every HTTP request. Here's how to get it:
109+
110+
<Tabs items={['Node.js', 'cURL']}>
111+
<Tabs.Tab>
112+
```javascript
113+
import { createBackendClient } from "@pipedream/sdk/server";
114+
115+
// Initialize the Pipedream client with the SDK
116+
const pd = createBackendClient({
117+
environment: PIPEDREAM_ENVIRONMENT,
118+
credentials: {
119+
clientId: PIPEDREAM_CLIENT_ID,
120+
clientSecret: PIPEDREAM_CLIENT_SECRET,
121+
},
122+
projectId: PIPEDREAM_PROJECT_ID
123+
});
124+
125+
// Get access token for MCP server auth
126+
const accessToken = await pd.rawAccessToken();
127+
128+
console.log(accessToken);
129+
```
130+
</Tabs.Tab>
131+
<Tabs.Tab>
132+
```bash
133+
curl -s -X POST https://api.pipedream.com/v1/oauth/token \
134+
-H "Content-Type: application/json" \
135+
-d '{
136+
"grant_type": "client_credentials",
137+
"client_id": "'$PIPEDREAM_CLIENT_ID'",
138+
"client_secret": "'$PIPEDREAM_CLIENT_SECRET'"
139+
}'
140+
```
141+
</Tabs.Tab>
142+
</Tabs>
143+
144+
#### Required headers
145+
146+
Include these headers in every HTTP request:
147+
148+
```javascript
149+
{
150+
Authorization: `Bearer ${PIPEDREAM_ACCESS_TOKEN}`,
151+
"x-pd-project-id": PIPEDREAM_PROJECT_ID, // proj_xxxxxxx
152+
"x-pd-environment": PIPEDREAM_ENVIRONMENT // development | production
153+
}
154+
```
155+
156+
### Self-host Pipedream's MCP server
157+
158+
#### Using the `Dockerfile`
159+
160+
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):
161+
162+
```console
163+
> docker build -t pipedream-connect .
164+
> docker run -d --name pd-mcp -p 3010:3010 --env-file .env pipedream-connect:latest
27165
```
28166

29-
#### Run the MCP server
167+
This exposes a generic MCP server at [http://localhost:3010/:external_user_id/:app](http://localhost:3010/:external_user_id/:app).
168+
169+
#### Start the server with Streamable HTTP Transport
30170

31-
Pipedream's MCP servers can run in two modes:
171+
```bash
172+
pnpm dev:http
173+
```
32174

33-
##### Stdio (for local testing)
175+
You can use the optional env var `PD_SDK_DEBUG` to print out all the requests and responses going to the Connect API:
34176

35177
```bash
36-
npx @pipedream/mcp stdio --app slack --external-user-id user123
178+
PD_SDK_DEBUG=true pnpm dev:http
37179
```
38180

39-
##### SSE (for hosting)
181+
#### Start the server with SSE
40182

41183
```bash
42184
npx @pipedream/mcp sse
@@ -46,13 +188,9 @@ This exposes routes at:
46188
- `GET /:external_user_id/:app` - App-specific SSE connection endpoint
47189
- `POST /:external_user_id/:app/messages` - App-specific message handler
48190

49-
Where:
50-
- `:external_user_id` is your user's unique identifier in your system
51-
- `:app` is the app slug (e.g., "slack", "github")
52-
53191
#### Customize for your needs
54192

55-
You can host and customize the MCP server for your specific requirements:
193+
You can also host and customize the MCP server for your specific requirements:
56194

57195
```bash
58196
# Clone the repo
@@ -71,4 +209,24 @@ npm run start:sse:prod
71209

72210
See the [MCP server README](https://github.com/PipedreamHQ/pipedream/blob/master/modelcontextprotocol/README.md) for detailed instructions on customization options.
73211

74-
</Steps>
212+
### Use the MCP inspector
213+
214+
The [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector) can be helpful when debugging tool calls.
215+
216+
```bash
217+
npx @modelcontextprotocol/inspector
218+
```
219+
220+
Enter the server URL:
221+
222+
If using Pipedream's remote server:
223+
224+
```
225+
https://mcp.pipedream.net/{external_user_id}/{app_slug}
226+
```
227+
228+
If running locally:
229+
230+
```
231+
http://localhost:3010/{external_user_id}/{app_slug}
232+
```

‎docs-v2/pages/connect/mcp/openai.mdx‎

Lines changed: 8 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@ import { Callout, Tabs, Steps } from 'nextra/components'
55
Access {process.env.PUBLIC_APPS}+ APIs and 10,000+ tools in OpenAI using Pipedream Connect. MCP makes it easy to extend the capabilities of any LLM or agent, and Pipedream offers drop-in support for [calling tools in OpenAI](https://platform.openai.com/docs/guides/tools?api-mode=responses) .
66

77
<Callout type="info">
8-
Pipedream Connect includes built-in user authentication for [every MCP server](https://mcp.pipedream.com), which means you don't need to build any authorization flows or deal with token storage and refresh in order to make authenticated requests on behalf of your users. [Learn more below](#account-connection).
8+
Pipedream Connect includes built-in user authentication for [every MCP server](https://mcp.pipedream.com), which means you don't need to build any authorization flows or deal with token storage and refresh in order to make authenticated requests on behalf of your users. [Learn more here](/connect/mcp/developers/#account-connections).
99
</Callout>
1010

11-
### Getting started
11+
## Getting started
1212

1313
<Steps>
1414

@@ -30,34 +30,13 @@ Now set the following environment variables (learn more about environments in Pi
3030
OPENAI_API_KEY=your_openai_api_key
3131
PIPEDREAM_CLIENT_ID=your_client_id
3232
PIPEDREAM_CLIENT_SECRET=your_client_secret
33-
PIPEDREAM_PROJECT_ID=your_project_id
34-
PIPEDREAM_ENVIRONMENT=development
33+
PIPEDREAM_PROJECT_ID=your_project_id # proj_xxxxxxx
34+
PIPEDREAM_ENVIRONMENT=development # development | production
3535
```
3636

3737
### Discover available MCP servers
3838

39-
Pipedream provides [{process.env.PUBLIC_APPS}+ APIs as MCP servers](https://mcp.pipedream.com) that can be used with OpenAI's tool calls. Each server corresponds to an app integration (like Notion, Gmail, or Slack) and has its own specific set of tools that you can expose to OpenAI.
40-
41-
<Tabs items={['List all apps', 'Search for a specific app']}>
42-
<Tabs.Tab>
43-
```javascript
44-
// Get all available apps (paginated)
45-
const apps = await pd.getApps();
46-
47-
// Each app has these key properties:
48-
// - name_slug: Used in the MCP server URL (e.g., "notion", "gmail", "slack")
49-
// - name: Display name (e.g., "Notion", "Gmail", "Slack")
50-
```
51-
</Tabs.Tab>
52-
<Tabs.Tab>
53-
```javascript
54-
// Search by app name
55-
const notionApps = await pd.getApps({ q: "notion" });
56-
const gmailApps = await pd.getApps({ q: "gmail" });
57-
const slackApps = await pd.getApps({ q: "slack" });
58-
```
59-
</Tabs.Tab>
60-
</Tabs>
39+
[See here](/connect/mcp/developers/#discover-available-mcp-servers) for guidance on discovering the apps Pipedream has available as MCP servers.
6140

6241
### Generate a model response in OpenAI with Pipedream MCP
6342

@@ -120,8 +99,6 @@ console.log(response);
12099
</Tabs.Tab>
121100
<Tabs.Tab>
122101
```bash
123-
# Complete example from start to finish
124-
125102
# Step 1: Get access token from Pipedream
126103
ACCESS_TOKEN=$(curl -s -X POST https://api.pipedream.com/v1/oauth/token \
127104
-H "Content-Type: application/json" \
@@ -164,24 +141,9 @@ curl -X POST https://api.openai.com/v1/chat/completions \
164141
}'
165142
```
166143
</Tabs.Tab>
167-
</Tabs>
144+
</Tabs>
168145
</Steps>
169146

170-
## Account Connection
171-
172-
One of the core features of Pipedream Connect and our MCP product is the ability for your users to easily connect their accounts without having to build any of the authorization flow or handle token storage.
147+
## Account connections
173148

174-
You can handle account connections in one of two ways in your app:
175-
176-
### Add a button in your UI
177-
- Use Pipedream's [frontend SDK](/connect/managed-auth/quickstart/#use-the-pipedream-sdk-in-your-frontend) to let users connect their account directly in your UI
178-
- You can see an example of this when you connect any account in [mcp.pipedream.com](https://mcp.pipedream.com)
179-
180-
### Return a link
181-
- Use [Connect Link ](/connect/managed-auth/quickstart/#or-use-connect-link) to let your users open a Pipedream hosted page to connect their account
182-
- There is no implementation required for this option since it's already handled in Pipedream's MCP server
183-
- If a user doesn't have a connected account that's required for a given tool call, we'll return a URL in the tool call response. For example:
184-
185-
```
186-
https://pipedream.com/_static/connect.html?token=ctok_xxxxxxx&connectLink=true&app=notion
187-
```
149+
[See here](/connect/mcp/developers/#account-connections) for more info.

0 commit comments

Comments
 (0)