how-to-guide

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

September 10, 2026 openai/plugins ↗

You integrate MCP servers with OpenAI plugins by declaring endpoints in a .mcp.json file, referencing it in the plugin manifest at .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 (lines 178-185).

Integration Architecture Overview

The integration follows a three-layer architecture:

  1. Configuration Layer: The .mcp.json file defines server URLs and transport protocols
  2. Manifest Layer: The plugin's .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 (lines 115-121).

Step-by-Step Integration Guide

Step 1: Declare the MCP Server in .mcp.json

Create a .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.

{
  "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 (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 file, pointing to the relative path of your .mcp.json configuration.

{
  "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 (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. The client handles connection management and protocol negotiation.

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 (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.

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.


# 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 (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 (lines 1034-1043).

Key Implementation Files in the Repository

Understanding the source structure helps troubleshoot integration issues:

Summary

  • MCP servers provide secure, standardized APIs that OpenAI agents consume through the @ai-sdk/mcp package
  • Configuration requires a .mcp.json file and a corresponding mcpServers entry in .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 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.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →