Best Practices for MCP Settings in OpenAI Plugins

Limit MCP operations to read-only calls with a maximum of 5 results, prioritize local API references over dynamic discovery, and centralize configuration in a root-level .mcp.json file to ensure secure, deterministic agent behavior.

The Model Context Protocol (MCP) standardizes how plugins expose structured tools to LLM agents across the openai/plugins ecosystem. Proper MCP configuration prevents unnecessary network overhead, reduces token consumption, and maintains deterministic execution paths. Following the implementation patterns from Wix, Vercel, and Metabase ensures your plugin integrates securely with agentic workflows.

Centralize Configuration in .mcp.json

Store all MCP connection parameters in a .mcp.json file at the plugin root. This convention, documented in plugins/metabase/README.md, allows the SDK to auto-load server URLs, authentication credentials, and default behavioral parameters without hardcoding sensitive values.

A minimal configuration follows this structure:

{
  "serverUrl": "https://my-plugin.example.com/mcp",
  "auth": {
    "type": "oauth",
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  },
  "defaultMaxResults": 5
}

The plugins/daloopa/README.md demonstrates this pattern for financial data endpoints, while plugins/build-ios-apps/.mcp.json provides a concrete implementation reference for local MCP configurations.

Enforce Result Limiting

Always constrain MCP search operations to maxResults: 5 or lower to prevent context window overflow. According to plugins/wix/skills/wix-app/SKILL.md, this limit keeps tool-calling responses concise and prevents excessive token usage during agent reasoning loops. Set this as the defaultMaxResults in your .mcp.json or explicitly pass the parameter in each call.

Prefer API References Over MCP Discovery

Agents should scan local API reference files before invoking MCP discovery tools. As specified in plugins/wix/skills/wix-app/SKILL.md, the skill must "Check API references first … use MCP only for gaps." This approach eliminates unnecessary network latency and ensures deterministic behavior when documentation is available locally.

Implement Read-Only MCP with Write Fallbacks

Restrict MCP usage to read operations such as list_projects, list_drains, or get_runtime_logs. For state-mutating actions, fall back to CLI commands or REST endpoints. The plugins/vercel/README.md establishes this "MCP-first, CLI-fallback" pattern because MCP servers typically expose read-only surfaces, while CLI tools provide full write capabilities.

Generate Static Tool Definitions

Avoid exposing raw MCP endpoints directly to LLMs. Instead, use the mcp-to-ai-sdk CLI to generate static tool definitions during the plugin publishing process. As documented in plugins/vercel/skills/ai-sdk/SKILL.md, this guarantees agents only invoke whitelisted methods and prevents schema drift.

Plugin-Specific Implementation Patterns

Wix App Constraints

Never invoke MCP for the WixSiteBuilder skill. The plugins/wix/skills/wix-app/SKILL.md explicitly warns that calling WixSiteBuilder via MCP duplicates build processes and creates conflicts. Instead, rely on the local reference files packaged with the skill.

Vercel SDK Integration

Initialize the MCP client using the stable @ai-sdk/mcp package. The plugins/vercel/skills/ai-sdk/SKILL.md recommends createMCPClient for automatic OAuth refresh and configuration loading from .mcp.json. This client handles token management without manual intervention.

Cloudflare Server Architecture

For plugins hosting their own MCP servers, follow the Cloudflare implementation pattern described in plugins/cloudflare/README.md. This involves building the MCP server on Cloudflare's edge infrastructure and documenting the API patterns separately from the client consumption logic.

Code Example: Implementing the MCP Client

The following TypeScript implementation demonstrates proper client initialization and constrained tool calling:

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

export async function fetchProjects() {
  // Automatically loads serverUrl and auth from .mcp.json
  const client = await createMCPClient();
  
  // Respects the maxResults limit to control token usage
  const result = await client.callTool("list_projects", {
    maxResults: 5
  });
  
  return result.projects;
}

The client automatically handles OAuth token refresh using the credentials stored in .mcp.json, eliminating the need for manual authentication logic in your skill implementation.

Summary

• Store configuration in .mcp.json at the plugin root to centralize endpoints and authentication.
• Limit results to 5 items per MCP call to minimize token consumption and response latency.
• Check local API references first before falling back to MCP discovery tools.
• Use MCP for read operations only, delegating writes to CLI or REST fallbacks.
• Generate static definitions using mcp-to-ai-sdk before publishing to enforce tool whitelisting.
• Avoid duplicate MCP calls for skills like WixSiteBuilder that manage their own execution context.

Frequently Asked Questions

What is the purpose of the .mcp.json file?

The .mcp.json file centralizes MCP server configuration, including the serverUrl, OAuth credentials, and default parameters like maxResults. Located at the plugin root, it allows the @ai-sdk/mcp client to auto-load connection details without hardcoding sensitive information in your source code, as demonstrated in plugins/metabase/README.md and plugins/daloopa/README.md.

When should I use MCP versus direct API calls?

Use MCP primarily for dynamic capability discovery and read-only operations where structured tool calling benefits agent reasoning. Prefer direct API calls or local reference files when the capability is static and documented, or when performing write operations. The plugins/wix/skills/wix-app/SKILL.md and plugins/vercel/README.md both emphasize checking local references first and using CLI fallbacks for mutations.

How do I prevent excessive token usage with MCP?

Set maxResults: 5 (or lower) in either your .mcp.json configuration or individual tool calls. This practice, documented in plugins/wix/skills/wix-app/SKILL.md, ensures that MCP responses remain concise and do not consume excessive context window space during agent execution loops.

Can I use MCP for write operations in OpenAI plugins?

Generally, no. MCP servers in the OpenAI plugins ecosystem are designed primarily for read-only operations such as listing resources or fetching logs. For write operations, implement a fallback to CLI tools or REST APIs. The plugins/vercel/README.md explicitly recommends this "MCP-first, CLI-fallback" pattern to ensure full functionality while maintaining the security benefits of read-only MCP surfaces.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}