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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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:
| Option | Type | Default | Purpose |
|---|---|---|---|
exaApiKey | string | server fallback key | Exa API key for search operations |
tools | string (comma list) | web_search_exa,web_fetch_exa | Restricts which tools are exposed |
debug | boolean | false | Enables 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-servernpm package can fail to run over stdio if the bundleddist/stdio.cjsends up with multiple shebang lines after a third-party build step. If you see shebang-related parse errors, rebuild with the project's ownnpm run buildscript. - 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
GETagainst the SSE stream receive405 Method Not Allowed. The hosted endpoint expects the protocol-appropriate transport handshake (typicallyPOST) 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
toolsparameter after upgrading.
See Also
- Tools Reference — full schema for every tool in the registry.
- Configuration Schema — JSON Schema for the
/.well-known/mcp-configendpoint. - Type Definitions —
src/types.tsrequest 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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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 Name | Default State | Purpose | Replacement / Status |
|---|---|---|---|
web_search_exa | enabled | Real-time web search with clean, ready-to-use content | Active |
web_fetch_exa | enabled | Extract content from a known URL | Active |
web_search_advanced_exa | disabled | Full-control search: category, domains, dates, text, highlights, summaries, subpages | Active (opt-in) |
get_code_context_exa | disabled | Code snippet and docs search | Deprecated → use web_search_exa |
company_research_exa | disabled | Company/organization research | Deprecated → use web_search_advanced_exa |
crawling_exa | disabled | URL extraction | Deprecated → use web_fetch_exa |
people_search_exa | disabled | People / profile search | Deprecated → use web_search_advanced_exa |
linkedin_search_exa | disabled | LinkedIn search | Deprecated → use web_search_advanced_exa |
deep_researcher_start | disabled | Start an async research task | Deprecated → Research API |
deep_researcher_check | disabled | Check async research status | Deprecated → Research API |
deep_search_exa | disabled | Query expansion + synthesized answer | Deprecated → 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.
| Property | Type | Default | Description |
|---|---|---|---|
exaApiKey | string | server fallback | Exa API key used for all upstream calls. Self-hosters must set this. Source: api/well-known-mcp-config.ts |
tools | string (CSV) | web_search_exa,web_fetch_exa | Comma-separated list of tool IDs to enable. Each value must be in AVAILABLE_TOOLS. Source: api/well-known-mcp-config.ts |
debug | boolean | false | Enable 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_exasupports an inlinecategory:<type>syntax (company,people,news,personal site,research paper) parsed from the free-formquerystring. See thecategoryMatchregex in src/tools/webSearch.ts. Each invocation creates a per-request logger keyed bytoolName-timestamp-random.web_search_advanced_exais the most powerful tool and accepts the full filter surface defined in src/types.ts:category,includeDomains/excludeDomains, ISO-8601startPublishedDate/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, thecompanycategory rejectsincludeDomainsand date filters and would return a 400 error if supplied.web_fetch_exaextracts content from explicit URLs and is the replacement for the deprecatedcrawling_exa.deep_search_exa(when enabled) accepts anobjective, optionalsearch_queries(≤5 entries, ≤5 words each), atypeofdeep(4–12s) ordeep-reasoning(12–50s),numResults, anoutputSchemafor structured output (max 10 properties, nesting depth 2), and asystemPromptup 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
toolsURL 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 thetoolsparameter 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 acceptsPOST-based handshakes; generic clients that try aGETover SSE will be rejected. Use the documentedclaude mcp add --transport httpform. - 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_helpprompt advertises no arguments, but some MCP client implementations rejectprompts/getcalls that omit theargumentsobject. The schema is defined in the handler, so clients that conform strictly to the JSON-RPC shape must sendarguments: {}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
Continue reading this section for the full explanation and source context.
Related Pages
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
| Tool | Default state | Replacement |
|---|---|---|
web_search_exa | enabled | — |
web_fetch_exa | enabled | — |
web_search_advanced_exa | disabled (opt-in via tools=) | — |
company_research_exa | disabled, deprecated | web_search_advanced_exa |
deep_search_exa | disabled, deprecated | web_search_advanced_exa |
deep_researcher_start / _check | disabled, deprecated | Exa 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:
- Local stdio via npm —
claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_exa,web_search_advanced_exa"for the hosted path, ornpx exa-mcp-serverafter configuringEXA_API_KEYfor the local binary. Source: README.md, npm.readme.md.
- 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).
- Tool-selective deployment — Use the
toolsquery 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 defaulttools=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
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
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:
| Property | Type | Purpose |
|---|---|---|
exaApiKey | string | Optional Exa AI key. The server ships with a fallback key; supplying your own is recommended for billing isolation. |
tools | string | Comma-separated list of tool IDs to enable. Empty = defaults (web_search_exa, web_fetch_exa). |
debug | boolean | Enables 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, requirescategory: "company"for discovery, and falls back tocategory: "news"or no category for deeper context. Source: README.md:158-189. - Personal Site Search — restricts to
web_search_advanced_exawithcategory: "personal site"; supports all filter parameters. Source: README.md:191-225. - Research Paper Search — restricts to
category: "research paper"; pairs well withincludeDomains: ["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/mcpreceive a405 Method Not Allowedbecause 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.cjsbuild 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/getrejects zero-argument prompts — Theweb_search_helpprompt declaresarguments: []but the server rejects calls that omit theargumentsfield. 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, andweb_fetch_exa. - Configuration & Deployment — API keys, environment variables, and the
?.well-known/mcp-configschema. - Exa API Types — TypeScript interfaces in
src/types.tsforExaSearchRequest,ExaSearchResult, andExaSearchResponse.
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.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
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.
Count of project-level external discussion links exposed on this manual page.
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.
- [[Regulatory Signals] exa-mcp-server is listed on the MCP Trust Registry](https://github.com/exa-labs/exa-mcp-server/issues/361) - github / github_issue
- MCTS Security Scan: 7 HIGH/CRITICAL findings — exec() call, injection su - github / github_issue
- Proposal: Free AI Agent identity verification for Exa MCP - github / github_issue
- prompts/get rejects omitted optional arguments for zero-argument prompt - github / github_issue
- Configuration risk requires verification - GitHub / issue
Source: Project Pack community evidence and pitfall evidence