Quick Start: OpenAI API

This is the path for building your own product on top of Amazon data. Your application calls the Responses API, the model calls Kuudo's Amazon tools, and you keep scoped auth, tool allow-lists, and approval behavior without writing an integration per Amazon API.

Connect the OpenAI Responses API to your private MCP server when you are building a custom agent, workflow, or application that should call MCP tools programmatically.

Your MCP server hostname is private to your deployment. It comes from your cloud provider, belongs to your environment, and is not shared across customers. Replace {your-private-mcp-host} with the private host shown in your dashboard.

Prerequisites

• A connected workspace with access to your private MCP server.
• A dashboard API key from the Keys tab.
• An OPENAI_API_KEY for the OpenAI project that will call the Responses API.
• A remote MCP server that supports Streamable HTTP or HTTP/SSE.

Add your MCP server as a Responses API tool

Pass your remote MCP server in the tools array with type: "mcp" and server_url.

export OPENAI_API_KEY="sk-proj_..."
export MCP_API_KEY="mcp_live_..."

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${OPENAI_API_KEY}" \
  -d '{
    "model": "gpt-5.5",
    "tools": [
      {
        "type": "mcp",
        "server_label": "private_mcp",
        "server_description": "Private workspace tools and data exposed through MCP.",
        "server_url": "https://{your-private-mcp-host}/mcp",
        "authorization": "'"${MCP_API_KEY}"'",
        "require_approval": "never"
      }
    ],
    "input": "List the tools available from my private MCP server."
  }'

The OpenAI request uses OPENAI_API_KEY. The MCP server uses MCP_API_KEY through the MCP tool's authorization field. Do not put your private MCP key in the top-level OpenAI Authorization header.

Tool discovery

When the request runs, the Responses API lists tools from your MCP server and may return an mcp_list_tools output item. If the model calls a tool, the response may also include an mcp_call item with the tool name, arguments, output, and any MCP error.

For long-running conversations, keep the mcp_list_tools item in the conversation context when possible so OpenAI does not have to fetch the same tool definitions on every turn.

Limit the available tools

If your MCP server exposes many tools, restrict the model to the tools this workflow needs:

{
  "type": "mcp",
  "server_label": "private_mcp",
  "server_url": "https://{your-private-mcp-host}/mcp",
  "authorization": "${MCP_API_KEY}",
  "allowed_tools": ["search", "fetch"],
  "require_approval": "never"
}

Use narrow tool sets for lower latency, lower token usage, and clearer tool selection.

Approval mode

The require_approval setting controls whether tool calls require your application to approve them before data is sent to the MCP server.

• "never": The model can call allowed tools without an approval round trip.
• "always": The model emits an approval request before each MCP tool call.
• Object form: Use OpenAI's approval controls to require approval only for selected tools.

Use approval for write-capable or sensitive tools. Only use "never" for servers and tool scopes you trust for that workflow.

Troubleshooting

Unauthorized or 401 errors

Make sure OPENAI_API_KEY is used only for the OpenAI request and MCP_API_KEY is passed through the MCP tool's authorization field. The MCP key must belong to the same workspace as the private MCP server.

Tools not discovered

Verify that server_url points to the reachable remote MCP endpoint and ends with /mcp for this deployment. The server must support Streamable HTTP or HTTP/SSE.

Approval requests appear unexpectedly

OpenAI requires approval by default for remote MCP data sharing. Set require_approval deliberately for each workflow and handle any mcp_approval_request output items in your application.

Slow responses

Filter with allowed_tools, keep mcp_list_tools in conversation context, and check network latency between OpenAI and your private host.

When to use this page

Use this API setup when you own the application code that calls OpenAI. If you want ChatGPT itself to connect to the MCP server, use the ChatGPT quick start. If you want OpenAI Codex to use the MCP server while working in a repository, use the Codex quick start.