# Best Practices for MCP Settings in OpenAI Plugins

> Discover best practices for MCP settings in OpenAI plugins. Optimize agent behavior with read-only calls, local API references, and centralized configuration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-06-06

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json)

Store all MCP connection parameters in a [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) file at the plugin root. This convention, documented in [`plugins/metabase/README.md`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/daloopa/README.md) demonstrates this pattern for financial data endpoints, while [`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/ai-sdk/SKILL.md) recommends `createMCPClient` for automatic OAuth refresh and configuration loading from [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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:

```typescript
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`](https://github.com/openai/plugins/blob/main/.mcp.json), eliminating the need for manual authentication logic in your skill implementation.

## Summary

- **Store configuration in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json) file?

The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/metabase/README.md) and [`plugins/daloopa/README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-app/SKILL.md) and [`plugins/vercel/README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) configuration or individual tool calls. This practice, documented in [`plugins/wix/skills/wix-app/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.