# How to Integrate MCP Servers with OpenAI Plugins: A Complete Guide

> Master integrating MCP servers with OpenAI plugins. Learn to declare endpoints, reference plugin manifests, and consume tools using the @ai-sdk/mcp client for seamless integration. Get the complete guide.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-10

---

**You integrate MCP servers with OpenAI plugins by declaring endpoints in a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file, referencing it in the plugin manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), and consuming the tools via the `@ai-sdk/mcp` client in your skills.**

The **Model Context Protocol (MCP)** provides a standardized way to expose external service APIs to OpenAI agents. According to the `openai/plugins` repository, this integration allows LLMs to invoke remote tools without handling raw credentials, using a declarative configuration that the AI SDK reads at runtime.

## What Are MCP Servers?

**MCP servers** expose tool-oriented APIs that OpenAI agents call like native SDK functions. They enable read-only or read/write interactions with services such as Vercel, Supabase, or Linear while keeping authentication tokens server-side. The protocol defines how tools are discovered, invoked, and how their schemas are communicated to the LLM.

In the `openai/plugins` codebase, MCP servers are stateless by default, treating each call independently. Stateful servers are supported but require agents to handle potential `ApplicationError` failures, as seen in the Temporal Python integration at [`plugins/temporal/skills/temporal-developer/references/python/integrations/openai-agents-sdk.md`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/python/integrations/openai-agents-sdk.md) (lines 178-185).

## Integration Architecture Overview

The integration follows a three-layer architecture:

1. **Configuration Layer**: The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file defines server URLs and transport protocols
2. **Manifest Layer**: The plugin's [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) references the MCP configuration via the `mcpServers` field
3. **Runtime Layer**: Skills import `createMCPClient` from `@ai-sdk/mcp` to fetch tool definitions and execute calls via `generateText`

Authentication is handled transparently—MCP servers using OAuth 2.1 receive tokens on-demand without the plugin code storing credentials, as implemented in the Vercel Connect workflow at [`plugins/vercel/skills/vercel-connect/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-connect/SKILL.md) (lines 115-121).

## Step-by-Step Integration Guide

### Step 1: Declare the MCP Server in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)

Create a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file in your plugin root to define the server endpoint and transport mechanism. This file specifies one or more MCP servers that your plugin will consume.

```json
{
  "servers": [
    {
      "name": "my-mcp",
      "url": "https://mcp.example.com/mcp",
      "transport": "streamable-http"
    }
  ]
}

```

*Reference*: See the MCP JSON specification in [`plugins/.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugins/.agents/skills/plugin-creator/references/plugin-json-spec.md) (line 19) for the complete schema.

### Step 2: Reference the Configuration in the Plugin Manifest

Add the `mcpServers` field to your [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file, pointing to the relative path of your [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) configuration.

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Demo plugin with MCP",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "skills": "./skills/"
}

```

*Example*: The **Codex Security** plugin manifest at [`plugins/codex-security/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/codex-security/.codex-plugin/plugin.json) (line 20) demonstrates this exact pattern.

### Step 3: Create an AI-SDK MCP Client

Inside your skill, import `createMCPClient` from `@ai-sdk/mcp` and instantiate it with the server name defined in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json). The client handles connection management and protocol negotiation.

```typescript
import { createMCPClient } from "@ai-sdk/mcp";
import { generateText } from "ai";

const mcp = createMCPClient({
  name: "my-mcp",               // matches the "name" in .mcp.json
  transport: "streamable-http", // optional if defined in .mcp.json
});

```

*Reference*: The Temporal AI-SDK integration at [`plugins/temporal/skills/temporal-developer/references/typescript/integrations/vercel-ai-sdk.md`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/typescript/integrations/vercel-ai-sdk.md) (lines 124-131) provides the full implementation.

### Step 4: Fetch and Use Tools in Your Skill

Call `await mcpClient.tools()` to retrieve the tool definitions from the MCP server. Pass these tools directly to `generateText` or similar AI SDK functions, allowing the LLM to discover and invoke remote capabilities.

```typescript
export const mySkill = async (input: string) => {
  const tools = await mcp.tools();   // fetch tool definitions from the server
  const result = await generateText({
    model: "gpt-4o-mini",
    prompt: `Answer the user request using the available tools.`,
    tools,                         // give the LLM the MCP-provided tools
  });
  return result;
};

```

*Reference*: The same Temporal example (line 157) shows how `mcp.tools()` returns the array required by the AI SDK.

### Step 5: Handle Authentication

When using services like Vercel Connect, authentication tokens are fetched on-demand by the MCP server. The client automatically forwards the appropriate OIDC token when the user runs a tool, eliminating the need to store credentials in your plugin code.

```bash

# Register an MCP server named "linear" with Vercel Connect

vercel connect create https://mcp.linear.app/mcp --name linear

# Retrieve a token for the connector (user-scoped or app-scoped)

vercel connect token linear/myagent --subject user

```

*Documentation*: See the Vercel Connect skill at [`plugins/vercel/skills/vercel-connect/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-connect/SKILL.md) (lines 115-121).

## Transport Options and Performance Considerations

When you integrate MCP servers with OpenAI plugins, you must select the appropriate transport protocol:

- **StreamableHTTPClientTransport** (`@ai-sdk/mcp`): Preferred for production due to faster performance and no persistent connections. This is the recommended approach for stateless operations.
- **SSE Transport**: Supported for backward compatibility but maintains persistent connections, making it less efficient for high-throughput scenarios.

**Tool Schema Alignment**: MCP servers use `inputSchema` and `output` fields instead of the older `parameters`/`result` convention. This alignment is mandatory for the AI SDK to auto-generate static tool definitions via the `mcp-to-ai-sdk` CLI, as documented in [`plugins/vercel/vercel.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/vercel.md) (lines 1034-1043).

## Key Implementation Files in the Repository

Understanding the source structure helps troubleshoot integration issues:

- **[`plugins/.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugins/.agents/skills/plugin-creator/references/plugin-json-spec.md)**: Defines the `mcpServers` field specification (line 19)
- **[`plugins/codex-security/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/codex-security/.codex-plugin/plugin.json)**: Live example of a plugin manifest referencing MCP servers (line 20)
- **[`plugins/temporal/skills/temporal-developer/references/typescript/integrations/vercel-ai-sdk.md`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/typescript/integrations/vercel-ai-sdk.md)**: Complete TypeScript implementation of MCP client creation and tool usage (lines 124-157)
- **[`plugins/vercel/skills/vercel-api/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/vercel-api/SKILL.md)**: Demonstrates LLM tool invocation against MCP-exposed endpoints (lines 90-102)
- **[`plugins/vercel/agents/ai-architect.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/agents/ai-architect.md)**: Shows how AI-architect agents wire MCP clients into plugin workflows

## Summary

- **MCP servers** provide secure, standardized APIs that OpenAI agents consume through the `@ai-sdk/mcp` package
- **Configuration** requires a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file and a corresponding `mcpServers` entry in [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)
- **Runtime integration** uses `createMCPClient()` to fetch tools and pass them to `generateText()`
- **Security** is handled via on-demand token fetching—credentials never reside in plugin code
- **Performance** is optimized using `StreamableHTTPClientTransport` for stateless server interactions

## Frequently Asked Questions

### What is the difference between stateless and stateful MCP servers?

Stateless MCP servers treat each tool call as an independent transaction, making them ideal for most API interactions and easier to scale. Stateful servers retain session data between calls, which is useful for multi-step workflows but requires your agent to handle `ApplicationError` exceptions when sessions expire or fail, as shown in the Temporal Python integration documentation.

### Do I need to store OAuth tokens in my plugin code to authenticate with MCP servers?

No. MCP servers that use OAuth 2.1 handle authentication by fetching tokens on-demand when the tool is invoked. The client forwards the appropriate token (such as a Vercel OIDC token) automatically during the request. This architecture ensures sensitive credentials never appear in your plugin source code or LLM context.

### Can I use MCP servers with the OpenAI Agents SDK in Python?

Yes. While the primary examples in the repository use TypeScript and the Vercel AI SDK, the `openai/plugins` repository includes Python integration patterns. The Temporal skill documentation at [`plugins/temporal/skills/temporal-developer/references/python/integrations/openai-agents-sdk.md`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/python/integrations/openai-agents-sdk.md) demonstrates how to handle MCP tool calls and error states in Python-based agents.

### What transport protocol should I use for production MCP integrations?

Use **StreamableHTTPClientTransport** for production deployments. It offers better performance than SSE because it doesn't require persistent connections, and it handles stateless operations efficiently. SSE transport remains available for backward compatibility but is generally discouraged for new implementations requiring high throughput or serverless environments.