@optimai/mcp-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

1. Install dependencies & build

cd /home/bfc/optimai/optimai-search-mcp
npm install
npm run build

2. Environment variables

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

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

Custom Host Config (Stdio)

Add to your MCP host configuration:

{
  "mcpServers": {
    "optimai-search": {
      "command": "node",
      "args": ["/home/bfc/optimai/optimai-search-mcp/dist/index.js"],
      "env": {
        "OPTIMAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Claude Desktop

Same format — add the block above to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Cursor

Add to .cursor/mcp.json in your project or the global Cursor MCP config.

Smoke Test (MCP Inspector)

OPTIMAI_API_KEY=sk-... npx @modelcontextprotocol/inspector node dist/index.js

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.