Doramagic Project Pack · Human Manual

exa-mcp-server

Exa MCP for web search and web crawling!

Overview & Installation

Related topics: Available Tools & Configuration, Client Integration & Agent Skills

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Option A — Hosted Remote MCP (no API key required)

Continue reading this section for the full explanation and source context.

Section Option B — Local stdio install (npm)

Continue reading this section for the full explanation and source context.

Section Enabling and Disabling Tools

Continue reading this section for the full explanation and source context.

Related topics: Available Tools & Configuration, Client Integration & Agent Skills

Overview & Installation

Purpose and Scope

exa-mcp-server is a Model Context Protocol (MCP) server that exposes Exa's AI-powered web search and crawling capabilities to MCP-compatible clients such as Claude Code, Claude Desktop, and other agentic tools. The package is published as exa-mcp-server on npm and is also available as a hosted remote MCP service at https://mcp.exa.ai/mcp Source: README.md:1-40. The server lets an LLM-driven agent perform real-time web searches, fetch page contents from known URLs, and (when explicitly enabled) run advanced searches with category filters, domain restrictions, date ranges, highlights, and summaries Source: README.md:40-80.

The project version 3.2.1 declares its MCP name as io.github.exa-labs/exa-mcp-server, which is the stable identifier MCP clients use to discover and authenticate the server Source: package.json:1-5. Its TypeScript entry point is compiled to a single CommonJS bundle at dist/stdio.cjs that is invoked when the package is run via npx or as a globally installed binary Source: package.json:25-32.

High-Level Architecture

The server is structured around a central tool registry and a set of independent tool modules. Each tool module exports a register*Tool function that wires up its MCP definition, input schema, and handler against a shared server instance.

flowchart LR
  Client[MCP Client<br/>Claude Code / Desktop] -->|stdio or HTTP| Handler[mcp-handler.ts<br/>server + transport]
  Handler --> Registry[availableTools registry<br/>enabled/disabled flags]
  Registry --> WS[web_search_exa]
  Registry --> WSA[web_search_advanced_exa]
  Registry --> WF[web_fetch_exa]
  Registry --> DR[deep_search_exa]
  Registry --> Dep[(Deprecated tools<br/>get_code_context_exa, etc.)]
  WS --> ExaAPI[Exa Search API]
  WSA --> ExaAPI
  WF --> ExaAPI
  DR --> ExaAPI

src/mcp-handler.ts defines an availableTools map that controls which tools are exposed at runtime. Two tools — web_search_exa and web_fetch_exa — are enabled by default; everything else, including web_search_advanced_exa, is disabled until the user opts in Source: src/mcp-handler.ts:1-30. The well-known configuration endpoint at api/well-known-mcp-config.ts advertises the same default behavior to MCP clients, listing web_search_exa, web_search_advanced_exa, and web_fetch_exa as the configurable values Source: api/well-known-mcp-config.ts:1-30.

Installation

There are two supported installation paths, and the README recommends the remote MCP for the easiest setup.

Option A — Hosted Remote MCP (no API key required)

Add the remote server to your MCP client using a transport URL. The most basic configuration uses the shared hosted instance:

https://mcp.exa.ai/mcp

You can optionally pass an API key and a comma-separated list of enabled tools via query parameters. The README shows the canonical example of enabling all three first-party tools and supplying a personal key Source: npm.readme.md:1-25:

https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa

Option B — Local stdio install (npm)

For local installs, configure your MCP client to launch the package via npx. The README provides a Claude Code configuration block that pins the package name and forwards the EXA_API_KEY environment variable Source: README.md:60-90:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

The build step bundles src/stdio-cli.ts with esbuild for Node 20, producing dist/stdio.cjs with a node shebang so it can be executed directly Source: package.json:25-35. The bin field maps the exa-mcp-server command to that bundle Source: package.json:18-22.

Enabling and Disabling Tools

The tools query parameter (remote) or the corresponding MCP config field (local) selects which entries from the availableTools registry are activated. Issue #48 ("Selecting tools after new release") reports a regression where users who relied on older tools selections had to update their configuration after the registry expanded, which is consistent with how the registry's enabled defaults are defined in src/mcp-handler.ts Source: src/mcp-handler.ts:1-30.

To replicate the previous default-plus-advanced behavior, explicitly enable web_search_advanced_exa in addition to the defaults.

Configuration Reference

The server accepts the following options, as documented by the well-known config schema Source: api/well-known-mcp-config.ts:10-50:

OptionTypeDefaultPurpose
exaApiKeystringserver fallback keyExa API key for search operations
toolsstring (comma list)web_search_exa,web_fetch_exaRestricts which tools are exposed
debugbooleanfalseEnables verbose logging for troubleshooting

x-available-values in the schema enumerates the supported tool identifiers, which match the keys in the availableTools registry Source: api/well-known-mcp-config.ts:1-12; src/mcp-handler.ts:1-30.

Known Installation Pitfalls

The community has surfaced several recurring issues worth checking against your environment:

  • stdio transport breakage (issue #65): the exa-mcp-server npm package can fail to run over stdio if the bundled dist/stdio.cjs ends up with multiple shebang lines after a third-party build step. If you see shebang-related parse errors, rebuild with the project's own npm run build script.
  • Remote endpoint instability (issue #108): users have reported intermittent downtime on mcp.exa.ai/mcp. When this happens, falling back to a locally installed instance with your own API key is the documented recovery path.
  • SSE compatibility (issue #86): generic MCP clients that attempt to open the remote endpoint with an HTTP GET against the SSE stream receive 405 Method Not Allowed. The hosted endpoint expects the protocol-appropriate transport handshake (typically POST) rather than a raw SSE GET.
  • Tool selection after upgrade (issue #48): newly added or renamed tools can change the effective default set; review your tools parameter after upgrading.

See Also

  • Tools Reference — full schema for every tool in the registry.
  • Configuration Schema — JSON Schema for the /.well-known/mcp-config endpoint.
  • Type Definitions — src/types.ts request and response shapes for the Exa API.

Source: https://github.com/exa-labs/exa-mcp-server / Human Manual

Available Tools & Configuration

Related topics: Overview & Installation, Client Integration & Agent Skills

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Tool Enabling Flow

Continue reading this section for the full explanation and source context.

Section Enabling Additional Tools

Continue reading this section for the full explanation and source context.

Related topics: Overview & Installation, Client Integration & Agent Skills

Available Tools & Configuration

The exa-mcp-server (version 3.2.1 per package.json) exposes a curated set of Model Context Protocol (MCP) tools that wrap the Exa AI search and crawling APIs. The tool set is intentionally configurable so that a single server binary can serve minimal default clients, advanced power-users, and backward-compatible legacy clients.

Purpose and Scope

The tool catalog is the contract between the MCP client (for example, Claude Code, Cursor, or a custom agent runtime) and the Exa backend. The server advertises only the tools that have been explicitly enabled, which keeps the model context small and avoids surprising the client with deprecated or irrelevant endpoints. The catalog and its toggles are defined in src/mcp-handler.ts as the availableTools registry, and are exposed for programmatic discovery through the JSON Schema at api/well-known-mcp-config.ts.

A key design property: even with zero configuration, the server is usable because a fallback EXA_API_KEY is embedded for the hosted remote endpoint (https://mcp.exa.ai/mcp). Self-hosters are expected to supply their own key, as documented in the exaApiKey schema field in api/well-known-mcp-config.ts.

Tool Catalog

The following table is derived directly from the availableTools registry in src/mcp-handler.ts and the "Available Tools" section of README.md.

Tool NameDefault StatePurposeReplacement / Status
web_search_exaenabledReal-time web search with clean, ready-to-use contentActive
web_fetch_exaenabledExtract content from a known URLActive
web_search_advanced_exadisabledFull-control search: category, domains, dates, text, highlights, summaries, subpagesActive (opt-in)
get_code_context_exadisabledCode snippet and docs searchDeprecated → use web_search_exa
company_research_exadisabledCompany/organization researchDeprecated → use web_search_advanced_exa
crawling_exadisabledURL extractionDeprecated → use web_fetch_exa
people_search_exadisabledPeople / profile searchDeprecated → use web_search_advanced_exa
linkedin_search_exadisabledLinkedIn searchDeprecated → use web_search_advanced_exa
deep_researcher_startdisabledStart an async research taskDeprecated → Research API
deep_researcher_checkdisabledCheck async research statusDeprecated → Research API
deep_search_exadisabledQuery expansion + synthesized answerDeprecated → use web_search_advanced_exa

The AVAILABLE_TOOLS list in api/well-known-mcp-config.ts is the canonical set of values advertised in the schema's x-available-values enumeration. The well-known schema intentionally advertises only the three non-deprecated tools (web_search_exa, web_search_advanced_exa, web_fetch_exa); deprecated tool IDs remain functional in the handler for compatibility but are not surfaced for new clients.

Tool Enabling Flow

flowchart LR
    A[Client connects to MCP endpoint] --> B{Configuration source}
    B -- "URL query string (?tools=...)" --> C[Parse comma-separated list]
    B -- "EXA_API_KEY env or header" --> D[Resolve API key]
    C --> E[Filter availableTools registry]
    D --> E
    E --> F[Register only enabled tools with MCP server]
    F --> G[Client sees filtered tool list]

Configuration Options

The server accepts configuration through three surfaces: URL query parameters on the remote endpoint, the JSON Schema at /.well-known/mcp-config, and a Zod-validated object passed to the stdio CLI. The three properties are listed below.

PropertyTypeDefaultDescription
exaApiKeystringserver fallbackExa API key used for all upstream calls. Self-hosters must set this. Source: api/well-known-mcp-config.ts
toolsstring (CSV)web_search_exa,web_fetch_exaComma-separated list of tool IDs to enable. Each value must be in AVAILABLE_TOOLS. Source: api/well-known-mcp-config.ts
debugbooleanfalseEnable debug logging via the log utility. Source: api/well-known-mcp-config.ts

Enabling Additional Tools

To opt in to web_search_advanced_exa, append the tools parameter to the remote endpoint URL, exactly as shown in README.md:

https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa

For the local stdio install, the same effect is achieved through claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa" as documented in the agent-skill snippets in README.md.

Per-Tool Behavior Highlights

  • web_search_exa supports an inline category:<type> syntax (company, people, news, personal site, research paper) parsed from the free-form query string. See the categoryMatch regex in src/tools/webSearch.ts. Each invocation creates a per-request logger keyed by toolName-timestamp-random.
  • web_search_advanced_exa is the most powerful tool and accepts the full filter surface defined in src/types.ts: category, includeDomains / excludeDomains, ISO-8601 startPublishedDate / endPublishedDate, includeText / excludeText (single-item arrays only), userLocation, moderation, additionalQueries, and content shaping options (text, context, summary, highlights, livecrawl, subpages). Some filters are restricted per category — for example, the company category rejects includeDomains and date filters and would return a 400 error if supplied.
  • web_fetch_exa extracts content from explicit URLs and is the replacement for the deprecated crawling_exa.
  • deep_search_exa (when enabled) accepts an objective, optional search_queries (≤5 entries, ≤5 words each), a type of deep (4–12s) or deep-reasoning (12–50s), numResults, an outputSchema for structured output (max 10 properties, nesting depth 2), and a systemPrompt up to 32 000 characters. See src/tools/deepSearch.ts.

Common Failure Modes and Community Notes

The community has surfaced several recurring failure modes that map directly to the configuration surface described above:

  • Tool selection regression after a release (issue #48): the tools URL parameter was the documented mechanism; clients that relied on the previous implicit defaults can be broken by a release that changes which tool IDs are advertised in the schema. The mitigation is to be explicit in the tools parameter rather than relying on defaults, per the schema in api/well-known-mcp-config.ts.
  • Remote endpoint 405 on HTTP GET (issue #86): the remote MCP endpoint (https://mcp.exa.ai/mcp) only accepts POST-based handshakes; generic clients that try a GET over SSE will be rejected. Use the documented claude mcp add --transport http form.
  • Multiple shebang lines in dist/stdio.cjs (issue #65): the build script in package.json prepends a shebang banner via esbuild; downstream tooling that re-bundles the artifact must strip duplicate shebangs or stdio transport will fail.
  • Zero-argument prompts (issue #358): the web_search_help prompt advertises no arguments, but some MCP client implementations reject prompts/get calls that omit the arguments object. The schema is defined in the handler, so clients that conform strictly to the JSON-RPC shape must send arguments: {} explicitly.

See Also

  • Exa MCP Server — Overview (project home)
  • Architecture & Transport (stdio vs HTTP, Agnost tracker, Vercel handler)
  • Tools: Web Search Advanced (full filter surface)
  • Type Definitions (request/response shapes)
  • External: Exa API Documentation

Source: https://github.com/exa-labs/exa-mcp-server / Human Manual

Architecture, Transports & Deployment

Related topics: Overview & Installation, Client Integration & Agent Skills

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Overview & Installation, Client Integration & Agent Skills

Architecture, Transports & Deployment

Overview

exa-mcp-server is a Model Context Protocol (MCP) server published by Exa Labs (io.github.exa-labs/exa-mcp-server, version 3.2.1) that exposes Exa's web search, advanced search, and URL-fetch capabilities as MCP tools. The project is a single npm package (exa-mcp-server) that is consumable in two distinct ways: as a local CLI binary that speaks the stdio transport, and as a remote HTTP/SSE server hosted at https://mcp.exa.ai/mcp. Both entry points share a common request-handling core and tool registry, so the same tool surface is reachable from Claude Code, Cursor, and other MCP clients regardless of transport. Source: package.json:1-15.

Transport Architecture

The repository ships two coexisting transports that share the same backing tool implementations.

flowchart LR
    Client[MCP Client<br/>Claude Code / Cursor] -->|stdio JSON-RPC| Stdio[src/stdio.ts<br/>stdio-cli.ts]
    Client -->|HTTPSSE POST| Remote[https://mcp.exa.ai/mcp<br/>api/mcp.ts]
    Stdio --> Handler[src/mcp-handler.ts<br/>Tool Registry]
    Remote --> Handler
    Handler --> Tools[Tool Modules<br/>webSearch, webSearchAdvanced,<br/>webFetch, deepSearch, ...]
    Tools --> Exa[Exa REST API]
    Tools --> Config[api/well-known-mcp-config.ts<br/>JSON Schema]

Stdio transport (local install). The package's ESM entry is ./src/stdio.ts (Source: package.json:6), and the build pipeline bundles src/stdio-cli.ts with esbuild into a CJS executable dist/stdio.cjs that is registered as the exa-mcp-server bin (Source: package.json:8-9, 22). This lets users run the server locally over stdin/stdout — the path most MCP launchers (Claude Code, Cursor, Smithery) use. Community issue #65 reports a regression where multiple shebang lines in .smithery/index.cjs broke stdio startup, indicating that the stdio path is the one most exposed to packaging-edge issues. Source: README.md, npm issue #65.

HTTP/SSE transport (remote). The hosted endpoint https://mcp.exa.ai/mcp accepts MCP traffic over HTTP. Configuration is passed through query parameters (exaApiKey, tools, debug), so no environment file is required. Community issue #86 documents that some generic MCP clients receive a 405 Method Not Allowed on plain GET against this endpoint — clients should use the streamable HTTP POST handshake instead of attempting legacy GET SSE upgrades. Source: README.md, npm issue #86.

Tool Registry and Configuration Surface

The MCP handler in src/mcp-handler.ts defines a static availableTools map where each entry is { name, description, enabled }. The default-enabled set is web_search_exa and web_fetch_exa; web_search_advanced_exa is registered but disabled by default, and a long tail of deprecated tools (get_code_context_exa, company_research_exa, deep_search_exa, crawling_exa, people_search_exa, linkedin_search_exa, deep_researcher_start, deep_researcher_check) remain in the registry for backwards compatibility but are explicitly marked deprecated with pointers to their replacements. Source: src/mcp-handler.ts:1-30, README.md

ToolDefault stateReplacement
web_search_exaenabled
web_fetch_exaenabled
web_search_advanced_exadisabled (opt-in via tools=)
company_research_exadisabled, deprecatedweb_search_advanced_exa
deep_search_exadisabled, deprecatedweb_search_advanced_exa
deep_researcher_start / _checkdisabled, deprecatedExa Research API

Discovery is standardized through api/well-known-mcp-config.ts, which serves a JSON Schema at /.well-known/mcp-config declaring the three valid URL parameters: exaApiKey (string), tools (comma-separated subset of the registered names), and debug (boolean, default false). The x-available-values hint enumerates the same three primary tools, and x-query-style: dot+bracket advertises how complex tool arguments should be encoded. Source: api/well-known-mcp-config.ts:1-50.

Each tool module uses zod schemas for argument validation. webSearch.ts accepts a free-form natural-language query plus numResults, and parses a category:(company|people|research paper|news|personal site) token out of the query string before dispatching to the Exa API. deepSearch.ts exposes objective, search_queries, type (deep or deep-reasoning), numResults, and optional outputSchema / systemPrompt for structured outputs — with explicit guidance that deep mode takes 4–12 s and deep-reasoning takes 12–50 s. Source: src/tools/webSearch.ts:1-30, src/tools/deepSearch.ts:1-30.

Build, Package, and Deployment

The npm package is authored as TypeScript ESM ("type": "module") but ships a single bundled CJS artifact. The build:stdio script runs esbuild with --platform=node --target=node20 --format=cjs, prefixes the bundle with a #!/usr/bin/env node shebang banner, and chmods the output executable — the standard pattern for distributing an MCP stdio server that must run as npx exa-mcp-server (Source: package.json:22). A separate build:vercel script (tsc) produces the typed output for the hosted HTTP entry point.

Deployment in practice is a choice between three patterns, each suited to a different client:

  1. Local stdio via npmclaude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa" for the hosted path, or npx exa-mcp-server after configuring EXA_API_KEY for the local binary. Source: README.md, npm.readme.md.
  1. Remote HTTP — Point any MCP client at https://mcp.exa.ai/mcp. No API key is strictly required because the server can fall back to a shared key, but supplying ?exaApiKey=… enables per-user rate limits and cost attribution (Source: api/well-known-mcp-config.ts:1-50).
  1. Tool-selective deployment — Use the tools query parameter to enable only a subset of registered tools, e.g. ?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa. This is the mechanism community issue #48 identified as having regressed during a release when the default tools= parsing changed. Source: README.md, issue #48.

Observability is wired through agnost's trackMCP and createConfig helpers imported in src/mcp-handler.ts, and a per-request logger built from toolName + timestamp + random suffix provides correlation IDs surfaced in tool responses. Community issue #108 ("mcp.exa.ai/mcp down?") demonstrates that availability of the hosted transport is operationally user-visible, so operators should monitor the remote endpoint independently of the npm package. Source: src/mcp-handler.ts:1-10, issue #108.

See Also

  • Tool Reference — full per-tool argument schemas and examples
  • Configuration & URL Parameters
  • Security & Deployment Hardening — discussion of MCTS findings (issue #359) and the MCP Trust Registry listing (issue #361)

Source: https://github.com/exa-labs/exa-mcp-server / Human Manual

Client Integration & Agent Skills

Related topics: Overview & Installation, Available Tools & Configuration, Architecture, Transports & Deployment

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Configuration Schema

Continue reading this section for the full explanation and source context.

Related topics: Overview & Installation, Available Tools & Configuration, Architecture, Transports & Deployment

Client Integration & Agent Skills

The Exa MCP server exposes a set of web-search, web-fetch, and research tools to MCP-compatible clients (Claude Code, Claude Desktop, Cursor, generic JSON-RPC clients). Integration happens through two complementary surfaces: (1) the runtime MCP protocol — a remote HTTP endpoint at https://mcp.exa.ai/mcp or a local stdio binary — and (2) bundled Agent Skills that teach the host agent *how* to use the tools for specific tasks. This page documents the configuration surface, the available tool registry, the skill-pack format, and the known failure modes reported by the community.

Connection Endpoints and Client Setup

Two transport options are supported. The preferred path is the remote MCP at https://mcp.exa.ai/mcp, which requires no local install or API key. Clients that need offline or self-hosted operation can fall back to the stdio transport published to npm as exa-mcp-server. The package declares module: ./src/stdio.ts and a bin entry pointing to dist/stdio.cjs, built with esbuild for Node 20 ("type": "module", "format": "cjs"). Source: package.json:4-22.

For Claude Code, the recommended install command is:

claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"

Passing the tools query parameter narrows the toolset to only what the client needs. Source: README.md:165-167.

Configuration Schema

The server publishes a JSON Schema at /.well-known/mcp-config so clients can discover the supported parameters. Source: api/well-known-mcp-config.ts:5-12. The schema accepts three properties:

PropertyTypePurpose
exaApiKeystringOptional Exa AI key. The server ships with a fallback key; supplying your own is recommended for billing isolation.
toolsstringComma-separated list of tool IDs to enable. Empty = defaults (web_search_exa, web_fetch_exa).
debugbooleanEnables verbose logging for troubleshooting.

The allowed tools values are the canonical IDs declared in AVAILABLE_TOOLS: web_search_exa, web_search_advanced_exa, web_fetch_exa. Source: api/well-known-mcp-config.ts:5-9. Tool selection also works through the older env-var mechanism, but community issue #48 ("Selecting tools after new release") reported a regression in the config syntax, so clients migrating to the remote URL should prefer the ?tools= query parameter. Source: issue #48.

Tool Registry and Default Set

The server's tool registry lives in src/mcp-handler.ts and is the single source of truth for which tools are registered, enabled by default, and exposed. Each entry maps a tool ID to a display name, a description, and a boolean enabled flag. Source: src/mcp-handler.ts:1-24.

graph LR
  A[MCP Client] -->|tools/list| B[mcp-handler.ts<br/>tool registry]
  B --> C[web_search_exa<br/>enabled: true]
  B --> D[web_fetch_exa<br/>enabled: true]
  B --> E[web_search_advanced_exa<br/>enabled: false]
  B --> F[deprecated tools<br/>enabled: false]
  A -->|tools/call| C
  A -->|tools/call| D
  A -->|tools/call| E

By default only web_search_exa (real-time web search) and web_fetch_exa (content extraction) are exposed. web_search_advanced_exa — the full Exa search API with categories, domain/date filters, highlights, summaries, and subpage crawling — is opt-in. The advanced tool accepts a query and numResults, and parses an inline category:<type> token (e.g. category:people, category:company) to narrow results. Source: src/tools/webSearch.ts:13-25.

Several legacy tools (get_code_context_exa, company_research_exa, people_search_exa, linkedin_search_exa, deep_search_exa, crawling_exa, deep_researcher_start, deep_researcher_check) remain in the registry with enabled: false for backwards compatibility. The deprecation table in README.md maps each to a current replacement or to the standalone Research API. Source: README.md:141-156.

Agent Skills for Claude Code

The repository ships a small library of reusable Agent Skills that teach Claude Code how to use Exa for specific research tasks. Each skill is a self-contained Markdown block of three parts: an install command for the MCP connection, a --- frontmatter block declaring the skill's name, description, and context: fork directive, and a body that constrains the model to a single tool and a single category value. Source: README.md:158-248.

Four skills are documented in README.md:

  • Company Research — restricts the model to web_search_advanced_exa, requires category: "company" for discovery, and falls back to category: "news" or no category for deeper context. Source: README.md:158-189.
  • Personal Site Search — restricts to web_search_advanced_exa with category: "personal site"; supports all filter parameters. Source: README.md:191-225.
  • Research Paper Search — restricts to category: "research paper"; pairs well with includeDomains: ["arxiv.org", "openreview.net"]. Source: README.md:227-248.
  • Financial Report Search — restricts to category: "financial report"; useful for SEC filings and earnings releases. Source: README.md:201-245.

A critical pattern is Token Isolation: every skill instructs the agent to never run Exa searches in main context, instead spawning Task agents that process results and return only distilled output. Source: README.md:170-175, 213-218(, ). This keeps the main conversation window clean regardless of result volume.

A universal array-size restriction is enforced across all category-based skills: includeText and excludeText accept only single-item arrays. Multi-item arrays trigger a 400 error from the Exa API. To match multiple terms, clients must put them in the query string or run separate searches. Source: README.md:166-170(, ). The company category additionally rejects includeDomains, excludeDomains, and all date filters. Source: README.md:175-180.

Common Integration Issues

Several community-reported failure modes are relevant to integrators:

  • Remote endpoint returns 405 on SSE GET — Generic MCP clients that attempt Server-Sent Events over HTTP GET against https://mcp.exa.ai/mcp receive a 405 Method Not Allowed because the endpoint expects POST-based JSON-RPC. Claude Code works because it uses POST; non-Claude clients must do the same. Source: issue #86.
  • Stdio transport broken by duplicate shebang — The .smithery/index.cjs build artifact ships with multiple shebang lines, which causes some stdio launchers to reject the file. Source: issue #65.
  • Availability incidents on mcp.exa.ai/mcp — Periodic outages of the remote endpoint have been reported. Source: issue #108.
  • prompts/get rejects zero-argument prompts — The web_search_help prompt declares arguments: [] but the server rejects calls that omit the arguments field. Source: issue #358.

For security-conscious integrators, the project has been independently audited. The MCTS scanner flagged 7 HIGH/CRITICAL findings (including an exec() call and injection surfaces in the lifecycle script), and the Regulatory Signals registry awarded it a Silver grade with a score of 79/100. Source: issue #359, issue #361.

See Also

  • Tools & Parameters — Detailed parameter reference for web_search_exa, web_search_advanced_exa, and web_fetch_exa.
  • Configuration & Deployment — API keys, environment variables, and the ?.well-known/mcp-config schema.
  • Exa API Types — TypeScript interfaces in src/types.ts for ExaSearchRequest, ExaSearchResult, and ExaSearchResponse.

Source: https://github.com/exa-labs/exa-mcp-server / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

medium Configuration risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Configuration risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Capability evidence risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Maintenance risk requires verification

May increase setup, validation, or first-run risk for the user.

Doramagic Pitfall Log

Found 10 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.host_targets | https://github.com/exa-labs/exa-mcp-server

2. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/exa-labs/exa-mcp-server/issues/358

3. Capability evidence risk: Capability evidence risk requires verification

  • Severity: medium
  • Finding: README/documentation is current enough for a first validation pass.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.assumptions | https://github.com/exa-labs/exa-mcp-server

4. Maintenance risk: Maintenance risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://github.com/exa-labs/exa-mcp-server

5. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: downstream_validation.risk_items | https://github.com/exa-labs/exa-mcp-server

6. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: risks.scoring_risks | https://github.com/exa-labs/exa-mcp-server

7. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/exa-labs/exa-mcp-server/issues/359

8. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/exa-labs/exa-mcp-server/issues/361

9. Maintenance risk: Maintenance risk requires verification

  • Severity: low
  • Finding: issue_or_pr_quality=unknown。
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://github.com/exa-labs/exa-mcp-server

10. Maintenance risk: Maintenance risk requires verification

  • Severity: low
  • Finding: release_recency=unknown。
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://github.com/exa-labs/exa-mcp-server

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 5

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using exa-mcp-server with real data or production workflows.

Source: Project Pack community evidence and pitfall evidence