Search MCP

Connect OptimAI Search to Codex, Claude Desktop, Cursor, and other MCP-compatible AI hosts.

@optimai-network/search-mcp is a Model Context Protocol server for the OptimAI External Search API. It lets an MCP-compatible AI host start searches, poll for results, list recent searches, and cancel running work.

Tools

Tool	Description
`optimai_start_search`	Start a search and return the search ID immediately. Searches commonly take 60-90 seconds; call `optimai_get_search` with the ID to fetch progress and results.
`optimai_search`	Convenience search that waits briefly for results. If the search is still running, it returns the search ID for `optimai_get_search`.
`optimai_get_search`	Fetch current status or result of a past search by ID.
`optimai_list_searches`	List recent searches, filterable by status and date.
`optimai_cancel_search`	Cancel a running or pending search.

Setup

Create or manage API keys at search.optimai.network/api-keys.

export OPTIMAI_API_KEY="sk_live_..."

The MCP server reads OPTIMAI_API_KEY at startup. Never commit this key to source control.

The published MCP server currently targets the production API base URL and uses Standard Search. It does not expose the direct API's search_mode: "agent" option. Use the API or x402 SDK when an agent needs explicit Agent/Crypto mode or wallet-backed x402 payment.

Codex CLI

export OPTIMAI_API_KEY="sk_live_..."

codex mcp add optimai-search \
  --env OPTIMAI_API_KEY="$OPTIMAI_API_KEY" \
  -- npx -y @optimai-network/search-mcp

Restart Codex, then run /mcp to confirm optimai-search is enabled.

Claude Desktop and Cursor

Use the same stdio server shape in Claude Desktop, Cursor, and other MCP hosts:

{
  "mcpServers": {
    "optimai-search": {
      "command": "npx",
      "args": ["-y", "@optimai-network/search-mcp"],
      "env": {
        "OPTIMAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Claude Desktop uses this format in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

Cursor can use the same format in .cursor/mcp.json in your project or in the global Cursor MCP config.

Input limits

query must be 1 to 1,000 characters.
optimai_search.timeout_seconds accepts 10 to 55 seconds and defaults to 45.
optimai_search.poll_interval_ms accepts 500 to 10,000 milliseconds and defaults to 2,000.
optimai_list_searches.limit accepts 1 to 100 records and defaults to 10.

optimai_start_search and optimai_search send the query to POST /external/v1/search; the MCP package does not currently let a caller override the API base URL. Use a direct API client when you need a different endpoint or environment.

GitHub Copilot CLI

Add the server interactively with /mcp add, or edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "optimai-search": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@optimai-network/search-mcp"],
      "env": {
        "OPTIMAI_API_KEY": "sk-your-key-here"
      },
      "tools": ["*"]
    }
  }
}

GitHub Copilot cloud agent

Add an environment secret or variable named COPILOT_MCP_OPTIMAI_API_KEY, then add this MCP configuration in the repository's Copilot cloud agent settings:

{
  "mcpServers": {
    "optimai-search": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@optimai-network/search-mcp"],
      "env": {
        "OPTIMAI_API_KEY": "$COPILOT_MCP_OPTIMAI_API_KEY"
      },
      "tools": [
        "optimai_start_search",
        "optimai_get_search",
        "optimai_list_searches"
      ]
    }
  }
}

Use tools: ["*"] if you want to expose every tool, including optimai_search and optimai_cancel_search.

Smoke test

Use MCP Inspector to verify the server starts and exposes the expected schema:

OPTIMAI_API_KEY=sk_live_... npx @modelcontextprotocol/inspector npx -y @optimai-network/search-mcp

Troubleshooting

Symptom	Check
The server exits immediately	Confirm `OPTIMAI_API_KEY` is set in the host environment and restart the host.
The host shows no OptimAI tools	Confirm the command is `npx -y @optimai-network/search-mcp`, then restart the host and inspect its MCP logs.
A blocking search times out	Use `optimai_start_search` followed by `optimai_get_search`; long searches commonly take 60–90 seconds.
A request is rejected	Check the query length, timeout, poll interval, and API-key permissions before retrying.

Use this safe host prompt when testing the integration:

You are a research agent with OptimAI Search tools.
When the user asks for current web or social information, start a search, poll
until it completes, then answer from the result and include its cited sources.

Recommended flow

Use optimai_start_search for reliable agent workflows. It creates a search and returns immediately with an ID. Then call optimai_get_search to check progress and retrieve the completed answer.

optimai_search is a convenience wrapper that starts a search and polls for a short time. It is useful for quick prompts, but long searches should use the start-and-poll flow.