OptimAI Search

MCP (Model Context Protocol) server that wraps the OptimAI External Search API, enabling any MCP-compatible AI host to run Web3-focused web searches.

---

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/results.
optimai_search	Convenience search that waits briefly for results. If still running, returns the search ID for optimai_get_search.
optimai_get_search	Fetch current status/result of a past search by ID
optimai_list_searches	List recent searches (filterable by status, date)
optimai_cancel_search	Cancel a running or pending search

---

Setup

Environment variables

Variable	Required	Description
OPTIMAI_API_KEY	✅	Your OptimAI External API key (X-API-Key)

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

The API base URL is hardcoded to https://api-onchain.optimai.network.

---

MCP Integrations

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

Then restart Codex and run /mcp to confirm optimai-search is enabled.

Claude Desktop, Cursor, and other stdio hosts

For a published npm install, add this to your MCP host configuration:

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

Claude Desktop uses the same 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

You can 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 (MCP Inspector)

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

Tests

npm test

npm test only starts the MCP server and validates the tool schema. It does not call live OptimAI API tools.

To intentionally run a live backend smoke test:

OPTIMAI_API_KEY=sk-... npm run test:live

---

Architecture Notes

• Recommended reliable flow: optimai_start_search creates a search and returns immediately with an ID. Use optimai_get_search to check progress and retrieve the completed answer.
• Blocking convenience flow: optimai_search creates a search then polls GET /:id every 2s until terminal status or local timeout. It defaults to 45s and is capped at 55s to stay below common MCP client request timeouts.
• Future streaming: src/client.ts has a TODO: streamSearch() stub. Upgrading to SSE only requires implementing that method and adding a new optimai_search_stream tool — the blocking tool is unaffected.
• Auth: API key is read from env at startup. Never logged or exposed in tool responses.