134 lines
2.4 KiB
Markdown
134 lines
2.4 KiB
Markdown
# MCP Integration Guide
|
|
|
|
**Last Updated**: 2025-10-25
|
|
|
|
Guide for integrating external tools using Model Context Protocol (MCP).
|
|
|
|
---
|
|
|
|
## What Is MCP?
|
|
|
|
MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. It allows connecting external tools like Stripe, databases, and custom APIs.
|
|
|
|
**Key Benefits:**
|
|
- ✅ Built into Responses API (no separate setup)
|
|
- ✅ Automatic tool discovery
|
|
- ✅ OAuth authentication support
|
|
- ✅ No additional cost (billed as output tokens)
|
|
|
|
---
|
|
|
|
## Basic MCP Integration
|
|
|
|
```typescript
|
|
const response = await openai.responses.create({
|
|
model: 'gpt-5',
|
|
input: 'Roll 2d6 dice',
|
|
tools: [
|
|
{
|
|
type: 'mcp',
|
|
server_label: 'dice',
|
|
server_url: 'https://dmcp.example.com',
|
|
},
|
|
],
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
```typescript
|
|
const response = await openai.responses.create({
|
|
model: 'gpt-5',
|
|
input: 'Create payment link',
|
|
tools: [
|
|
{
|
|
type: 'mcp',
|
|
server_label: 'stripe',
|
|
server_url: 'https://mcp.stripe.com',
|
|
authorization: process.env.STRIPE_OAUTH_TOKEN, // ✅
|
|
},
|
|
],
|
|
});
|
|
```
|
|
|
|
**Important:** API does NOT store tokens. Provide with each request.
|
|
|
|
---
|
|
|
|
## Popular MCP Servers
|
|
|
|
- **Stripe**: https://mcp.stripe.com
|
|
- **Database MCP**: Custom servers for PostgreSQL, MySQL, MongoDB
|
|
- **Custom APIs**: Build your own MCP server
|
|
|
|
---
|
|
|
|
## Building Custom MCP Server
|
|
|
|
MCP server must implement:
|
|
|
|
### 1. List Tools Endpoint
|
|
|
|
```typescript
|
|
// POST /mcp/list_tools
|
|
{
|
|
tools: [
|
|
{
|
|
name: 'get_weather',
|
|
description: 'Get weather for a city',
|
|
input_schema: {
|
|
type: 'object',
|
|
properties: {
|
|
city: { type: 'string' },
|
|
},
|
|
required: ['city'],
|
|
},
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
### 2. Call Tool Endpoint
|
|
|
|
```typescript
|
|
// POST /mcp/call_tool
|
|
Request: {
|
|
name: 'get_weather',
|
|
arguments: { city: 'San Francisco' }
|
|
}
|
|
|
|
Response: {
|
|
result: {
|
|
temperature: 72,
|
|
condition: 'sunny',
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
```typescript
|
|
try {
|
|
const response = await openai.responses.create({
|
|
model: 'gpt-5',
|
|
input: 'Use tool',
|
|
tools: [{ type: 'mcp', server_url: '...', authorization: '...' }],
|
|
});
|
|
} catch (error: any) {
|
|
if (error.type === 'mcp_connection_error') {
|
|
console.error('Server connection failed');
|
|
}
|
|
if (error.type === 'mcp_authentication_error') {
|
|
console.error('Invalid token');
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
**Official MCP Docs**: https://platform.openai.com/docs/guides/tools-connectors-mcp
|