Skip to content

Danny/connect docs mcp 1 #16732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 21, 2025
Merged

Danny/connect docs mcp 1 #16732

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
513c2f1
Update openai.mdx
dannyroosevelt May 20, 2025
e998f82
Update pnpm-lock.yaml
dannyroosevelt May 20, 2025
2ce6143
Merge branch 'master' into danny/connect-docs-mcp-1
dannyroosevelt May 20, 2025
b4e8801
Update openai.mdx
dannyroosevelt May 20, 2025
be06b99
Merge branch 'danny/connect-docs-mcp-1' of github.com:PipedreamHQ/pip…
dannyroosevelt May 20, 2025
e2f6476
Merge branch 'danny/connect-docs-mcp-1' of github.com:PipedreamHQ/pip…
dannyroosevelt May 20, 2025
a7a11c8
Update pnpm-lock.yaml
dannyroosevelt May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 92 additions & 53 deletions docs-v2/pages/connect/mcp/openai.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,105 +1,142 @@
import { Callout, Tabs } from 'nextra/components'
import { Callout, Tabs, Steps } from 'nextra/components'

# Using Pipedream MCP with OpenAI

Access {process.env.PUBLIC_APPS}+ APIs and 10,000+ tools in OpenAI using Pipedream MCP with the [OpenAI Responses API](https://platform.openai.com/docs/guides/tools?api-mode=responses). MCP makes it easy to extend the capabilties of any LLM or agent, and Pipedream offers drop-in support for OpenAI.
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) .

<Callout type="info">
Pipedream MCP includes built-in user authentication for [every integrated API](https://pipedream.com/apps/), which means you don't need to build any authorization flows or think about token storage or refresh. [Learn more here](#account-connection).
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).
</Callout>

## Getting Started
### Getting started

<Steps>

### Set up your environment

To use Pipedream MCP with your own users, you need the following:

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

<Callout type="info">
These are requiremnents for you, the developer. Your users do **not** need to sign up for Pipedream in order to connect their accounts in your app or agent.
These are requirements for you, the developer. Your users do **not** need to sign up for Pipedream in order to connect their accounts in your app or agent.
</Callout>

#### Set up environment variables

Set the following environment variables (learn more about environments in Pipedream Connect [here](/connect/managed-auth/environments/)):
Now set the following environment variables (learn more about environments in Pipedream Connect [here](/connect/managed-auth/environments/)):

```bash
OPENAI_API_KEY=your_openai_api_key
PIPEDREAM_CLIENT_ID=your_client_id
PIPEDREAM_CLIENT_SECRET=your_client_secret
PIPEDREAM_PROJECT_ID=your_project_id
PIPEDREAM_ENVIRONMENT=development
```
Comment on lines 29 to 35
Copy link
Contributor

@coderabbitai coderabbitai bot May 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Add PUBLIC_APPS to environment setup
You reference process.env.PUBLIC_APPS earlier but haven’t listed it here. Consider adding:

PUBLIC_APPS=your_public_apps_count

so readers know to define it.

🤖 Prompt for AI Agents 
In docs-v2/pages/connect/mcp/openai.mdx around lines 29 to 35, the environment
variable PUBLIC_APPS is referenced but not included in the setup instructions.
Add a line defining PUBLIC_APPS in the environment variables section, for
example, PUBLIC_APPS=your_public_apps_count, to ensure users know to define it.


### Examples
### Discover available MCP servers

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.

<Tabs items={['List all apps', 'Search for a specific app']}>
<Tabs.Tab>
```javascript
// Get all available apps (paginated)
const apps = await pd.getApps();

// Each app has these key properties:
// - name_slug: Used in the MCP server URL (e.g., "notion", "gmail", "slack")
// - name: Display name (e.g., "Notion", "Gmail", "Slack")
```
</Tabs.Tab>
<Tabs.Tab>
```javascript
// Search by app name
const notionApps = await pd.getApps({ q: "notion" });
const gmailApps = await pd.getApps({ q: "gmail" });
const slackApps = await pd.getApps({ q: "slack" });
```
</Tabs.Tab>
</Tabs>

<Tabs items={['JavaScript', 'cURL']}>
### Generate a model response in OpenAI with Pipedream MCP

Below is an end to end example showing how to:
1. Initialize the Pipedream SDK
2. Find the relevant MCP server
3. Send a prompt to OpenAI with the MCP server as a tool call

<Tabs items={['Node.js', 'cURL']}>
<Tabs.Tab>
```javascript
import OpenAI from "openai";
import OpenAI from 'openai';
import { createBackendClient } from "@pipedream/sdk/server";

const externalUserId = "abc-123" // Unique ID in your system to identify the user

// Initialize the Pipedream SDK
// Initialize the Pipedream client with the SDK
const pd = createBackendClient({
environment: PIPEDREAM_ENVIRONMENT,
credentials: {
clientId: PIPEDREAM_CLIENT_ID,
clientSecret: PIPEDREAM_CLIENT_SECRET,
},
environment: PIPEDREAM_ENVIRONMENT,
projectId: PIPEDREAM_PROJECT_ID,
projectId: PIPEDREAM_PROJECT_ID
});

const { token } = await pd.createConnectToken({
external_user_id: externalUserId,
})
// Find the app to use for the MCP server
// For this example, we'll use Notion
const apps = await pd.getApps({ q: "notion" });
const appSlug = apps.data[0].name_slug; // e.g., "notion"

// Get access token for MCP server auth
const accessToken = await pd.rawAccessToken();

// Send the unique ID that you use to identify this user in your system
const externalUserId = 'abc-123'; // Used in MCP URL to identify the user

// Initialize OpenAI client
const client = new OpenAI();
Comment on lines +96 to 97
Copy link
Contributor

@coderabbitai coderabbitai bot May 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Include OPENAI_API_KEY in OpenAI client
new OpenAI() needs the API key context. Update to:

- const client = new OpenAI();
+ const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// Initialize OpenAI client
const client = new OpenAI();
// Initialize OpenAI client
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
🤖 Prompt for AI Agents 
In docs-v2/pages/connect/mcp/openai.mdx around lines 96 to 97, the OpenAI client
is initialized without passing the required API key. Update the client
initialization to include the OPENAI_API_KEY by passing it as a parameter or
configuration option to the OpenAI constructor to ensure proper authentication.


// Make the OpenAI request with the MCP server
const response = await client.responses.create({
model: "gpt-4.1",
model: 'gpt-4.1',
tools: [
{
"type": "mcp",
"server_label": "Notion",
"server_url": `https://mcp.pipedream.net/${externalUserId}/notion`,
"headers": {
"Authorization": `Bearer ${token}`
type: 'mcp',
server_label: 'Notion',
server_url: `https://mcp.pipedream.net/${externalUserId}/${appSlug}`,
headers: {
Authorization: `Bearer ${accessToken}`,
"x-pd-project-id": PIPEDREAM_PROJECT_ID,
"x-pd-environment": PIPEDREAM_ENVIRONMENT
},
"require_approval": "never"
},
require_approval: 'never'
}
],
input: "Summarize my most recently created Notion doc for me and help draft an email to our customers"
})
input: 'Summarize my most recently created Notion doc for me and help draft an email to our customers'
});

console.log(response);
```
</Tabs.Tab>
<Tabs.Tab>
```bash
# Step 1: Authenticate to the Pipedream API
curl -X POST https://api.pipedream.com/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "$PIPEDREAM_CLIENT_ID",
"client_secret": "$PIPEDREAM_CLIENT_SECRET"
}'
# Complete example from start to finish

# Store the access_token from the response

# Step 2: Get a short-lived Connect Token
curl -X POST https://api.pipedream.com/v1/connect/$PIPEDREAM_PROJECT_ID/tokens \
# Step 1: Get access token from Pipedream
ACCESS_TOKEN=$(curl -s -X POST https://api.pipedream.com/v1/oauth/token \
-H "Content-Type: application/json" \
-H "X-PD-Environment: $PIPEDREAM_ENVIRONMENT" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
"external_user_id": "abc-123"
}'
"grant_type": "client_credentials",
"client_id": "'$PIPEDREAM_CLIENT_ID'",
"client_secret": "'$PIPEDREAM_CLIENT_SECRET'"
}' | jq -r .access_token)

# Store the token from the response
# Step 2: Find the app to use for MCP server
# Search for the Notion app
APP_SLUG=$(curl -s -X GET "https://api.pipedream.com/v1/apps?q=notion" \
-H "Authorization: Bearer $ACCESS_TOKEN" | jq -r '.data[0].name_slug')

# Step 3: Call OpenAI with the MCP Server
# Step 3: Make request to OpenAI with MCP tool
curl -X POST https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
Expand All @@ -115,9 +152,11 @@ curl -X POST https://api.openai.com/v1/chat/completions \
{
"type": "mcp",
"server_label": "Notion",
"server_url": "https://mcp.pipedream.net/abc-123/notion",
"server_url": "https://mcp.pipedream.net/abc-123/'$APP_SLUG'",
"headers": {
"Authorization": "Bearer $CONNECT_TOKEN"
"Authorization": "Bearer '"$ACCESS_TOKEN"'",
"x-pd-project-id": "$PIPEDREAM_PROJECT_ID",
"x-pd-environment": "$PIPEDREAM_ENVIRONMENT"
},
"require_approval": "never"
}
Expand All @@ -126,11 +165,11 @@ curl -X POST https://api.openai.com/v1/chat/completions \
```
</Tabs.Tab>
</Tabs>

</Steps>

## Account Connection

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, etc.
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.

You can handle account connections in one of two ways in your app:

Expand All @@ -140,7 +179,7 @@ You can handle account connections in one of two ways in your app:

### Return a link
- Use [Connect Link ](/connect/managed-auth/quickstart/#or-use-connect-link) to let your users open a Pipedream hosted page to connect their account
- There isn't any implementation required for this option since it's already handled in Pipedream's MCP server
- There is no implementation required for this option since it's already handled in Pipedream's MCP server
- 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:

```
Expand Down
11 changes: 9 additions & 2 deletions pnpm-lock.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading