Prefer hosted Exa MCP in the integration catalog

Open Beginner friendly
  • Is something wrong?
#887 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
json, python
Domain
devtools

Research direction

Start with integrations/catalog/exa.json, using the datadog and huggingface entries as patterns, and check integrations/catalog.schema.json for valid fields. Add a hosted shttp option at https://mcp.exa.ai/mcp as the first connection option, with an optional password header x-api-key, and keep the npx stdio option after it. Done when npm run build:integrations leaves no unintended diff and tests/test_integration_catalog_in_sync.py passes.

Written by the indexing model from the issue text.

Description

priority:low ready-for-dev

Make https://mcp.exa.ai/mcp the default Exa connection so people don’t need to run it locally. Keep npx as an alternative, with optional API-key support for hosted usage.

built in researcher stays unchanged.

OpenHands AI triage

The following comments and acceptance criteria were added by the OpenHands AI agent.

Triage

The request maps to a single-file catalog change. Per the root AGENTS.md, integrations/catalog/*.json is the hand-authored source of truth for integrations, and the integrations README defines the first connectionOptions entry as the preferred default, so "hosted by default" means listing a hosted streamable-HTTP option first in integrations/catalog/exa.json. The hosted endpoint was verified live (keyless MCP handshake and tools/list return web_search_exa and web_fetch_exa), and Exa's official MCP docs document the hosted URL, a keyless free tier, OAuth via ?login, and API-key auth sent as the x-api-key header. The hosted option follows the catalog's existing datadog precedent (named header fields with auth.strategy: "none"), with the key field optional per this issue, and keyless connectability declared like the huggingface entry.

Scope: integrations/catalog/exa.json only, plus regenerating integrations/catalog-index.js with npm run build:integrations as AGENTS.md requires.

Non-goals: no changes to other integrations, client/app code, or the built-in researcher; no hosted OAuth connection option (Exa's ?login OAuth stays a documentation note only); no catalog schema changes; the npx stdio option and its required EXA_API_KEY field stay unchanged; no migration is needed since the catalog change only affects the default presented for new connections, and existing saved connections keep their chosen option.

Acceptance Criteria
  • integrations/catalog/exa.json lists, as its first connectionOptions entry, a hosted MCP option with provider: "mcp", transport.kind: "shttp", and transport.url: "https://mcp.exa.ai/mcp", so clients applying the documented "first option is the preferred default" contract present hosted Exa as the default connection.
  • The hosted option supports keyless and API-key use: the Exa API key is sent as the x-api-key request header (not the Authorization header) and is optional, declared via the catalog's named header-field mechanism (transport.headerFields with type: "password", required: false, matching the datadog entry's pattern) with keyless connectability declared via apiKeyOptional as in the huggingface entry; the field's helper text and link resolve and match Exa's documented instructions for creating an API key.
  • The existing npx stdio option (command: "npx", args: ["-y", "exa-mcp-server"], EXA_API_KEY env field) remains present and unchanged as a later connection option.
  • The edited entry is valid: JSON Schema validation against integrations/catalog.schema.json passes, the entry validates through openhands_extensions.IntegrationCatalogEntry, and npm run build:integrations regenerates integrations/catalog-index.js leaving no unintended diff.
  • uv sync --group test && uv run pytest -q tests/test_integration_catalog_in_sync.py passes.
  • Live keyless check: connecting to https://mcp.exa.ai/mcp over streamable HTTP lists tools including web_search_exa and web_fetch_exa (verified feasible from a direct IPv4 connection; evidence is the observed tool names via the SDK create_mcp_tools path or an equivalent scripted MCP handshake). With an API key set in the x-api-key header, agent_run is additionally advertised; verify when a key is available, otherwise skip per the tests/test_live_integration_smoke.py convention.
  • docsUrl resolves to the live Exa MCP documentation page (the current https://docs.exa.ai/reference/exa-mcp redirects to https://exa.ai/docs/get-started/exa-mcp; updating docsUrl to the canonical URL within the same file is in scope).
Dominant language
Python
Stars
176
Forks
124
Avg merge
1d 15h
Merged PRs (30d)
60

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenHands/extensions

All issues in OpenHands/extensions

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.