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

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

Codex CLI

export OPTIMAI_API_KEY="sk-..."

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.

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-... npx @modelcontextprotocol/inspector npx -y @optimai-network/search-mcp

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.