Purpose and audience

This spec is for AI and agent teams connecting LLMs and autonomous agents to the live web through Nimble's hosted Model Context Protocol (MCP) server. Any MCP-compatible host, including Claude, ChatGPT, Codex, Cursor, VS Code, and agent frameworks, can call Nimble's web search and retrieval tools directly and get back cited, structured results.

For installation, authorization, and a live verification call, start with Nimble Agent Setup.

What the MCP server gives an agent

Nimble is web search and retrieval for AI agents. Through MCP, an agent can:

• Search the live web and get ranked results with page content

• Extract clean content or typed fields from a known URL

• Run Extraction Templates for normalized data from popular sources

• Map and Crawl a site to discover and retrieve whole sections

• Delegate research to Web Search Agents and get back a cited answer or a schema-matched dataset

Connect and authenticate

• Server URL: https://mcp.nimbleway.com/mcp, using Streamable HTTP transport. Every tool name is prefixed nimble_, and tools are auto-discovered by the client.

• OAuth 2.1 with PKCE (recommended): clients that support OAuth discover the flow from the server, open the browser, and store and refresh the token themselves. There is no key to paste, rotate, or leak. Scopes: nimble:read, nimble:write, offline_access, openid. Revoke access by disconnecting the client or from your Nimble account.

• API key (fallback): for clients without OAuth, pass Authorization: Bearer <NIMBLE_API_KEY>. Create keys in Settings → API Keys, and issue a separate key per project.

Standard MCP config for clients with OAuth (no header needed):

{
  "mcpServers": {
    "nimble": {
      "type": "http",
      "url": "https://mcp.nimbleway.com/mcp"
    }
  }
}

Install by host

Per-client setup details are in the Nimble MCP Server docs and Plugin Installation. For a guided, agent-run setup, see Nimble Agent Setup.

MCP or the CLI?

MCP routes results through the model's context window, so large results consume tokens quickly. For bulk retrieval, such as crawling a whole site, the Nimble CLI (npm i -g @nimble-way/nimble-cli, authenticated with NIMBLE_API_KEY) writes results to a file instead. The CLI and SDKs also reach products the MCP server does not carry: SERP, Media, Domain Knowledge, and Jobs.

Nimble Docs MCP server

A separate, public MCP server at https://docs.nimbleway.com/mcp gives AI tools searchable access to the full Nimble documentation through one tool, search_nimble_docs. No API key is required. In Claude Code: claude mcp add --transport http nimble-docs https://docs.nimbleway.com/mcp.

Tool reference

Routing guidance

Agents get the best results when they pick the right tool for the task:

1. Single closed lookup: who or what at a glance, a filing or page pointer → nimble_search (with include_answer for a direct answer).

2. Named site plus a direct item: an Amazon ASIN, a Google Maps query, a specific URL → check Extraction Templates first, then nimble_extract.

3. Research, enrichment, or dataset building: "find every…", "enrich this list…", "brief me on…" → a Web Search Agent. Choose the mode (research, enrichment, or dataset building) and set effort from the task: low or medium for quick asks, high as the default when several fields need digging, and x-high or max for complex multi-faceted profiles.

4. Whole site section: nimble_map, then nimble_crawl_run.

Reference loop: Search → Retrieve → Reason → Verify

Web Search Agents run this whole loop for you, and they learn which sources and retrieval paths work. Recurring tasks get faster, more accurate, and up to 50% cheaper over time.

Vector and RAG pipeline fit

• Collection: use Search, Extract, or Crawl for documents, and Web Search Agents for structured datasets. Chunk with deterministic IDs (URL + hash + segment).

• Indexing: push to your vector store and a relational mirror (Delta or Snowflake) for governance queries. Store the source URL, capture time, locale, and confidence.

• Refresh: set TTLs by source type, for example 15 minutes for competitive prices, 1–4 hours for reviews, and daily for documentation. Re-embed only changed chunks.

• Delivery: results return through the API, or land in Databricks, Snowflake, or S3/GCS.

Guardrails to reduce hallucinations

• Citations first: require a source URL and capture time for every retrieved fact; enforce "no source, no claim" in prompts. Web Search Agents return per-claim citations with verbatim excerpts.

• Confidence thresholds: every Web Search Agent run returns a trust report that grades each claim high, medium, or low under fixed rules: a primary source or corroboration across two or more different domains grades high, a single secondary source grades medium, and no usable citation or a schema-validation failure grades low. Accept high automatically, spot-check medium, and route low to human review. A cited null is a verified absence and grades high. Trust docs

• Schema enforcement: define strict output schemas and reject records that fail validation.

• Source controls: restrict or prefer domains with include and exclude filters and Search Plans.

• Corroboration: for high-stakes facts, require agreement across two or more sources.

Domain examples

• AI developer platforms: Qodo replaced a static search index with Web Search Agents to validate code against current libraries and docs. The result was fewer support tickets and higher satisfaction. Case study

• GTM and revenue tech: Alta runs millions of pages a day with >99% job success and 3–4× deeper context for its agents. Case study

• Retail and CPG: pricing, digital shelf, and reviews research with Extraction Templates and Web Search Agents. See Retail & CPG.

• Finance: company and sector research with citations. See Alternative Data for Funds.

Benchmarks

• 1 overall on the DRACO deep-research benchmark (Nimble x-high: 74.0% overall, 71.6% factual accuracy)

• Self-learning: +4.4 points from run 1 to run 3 across four repeat-use domains

• Extraction: 90% completeness and 99.1% fetch success across 5,856 URLs

See Nimble Benchmarks.

Security, privacy, and compliance

Customers are controllers; Nimble acts primarily as a processor with DPAs, SOC 2 Type II, and zero-trust controls. Zero Data Retention is available on enterprise plans. Nimble collects public web data only. Trust Center

Pilot checklist (about 90 minutes)

1. Connect your agent host to Nimble's MCP server (Agent Setup).

2. Verify nimble_search and nimble_extract with a test query.

3. Define the facts your agent needs and an output schema.

4. For repeat research, create a Web Search Agent with that schema and run it at low effort for a preview.

5. Add guardrails: citations required, a confidence threshold, and source controls.

6. Index results to your vector store with source metadata and TTLs.

7. Track KPIs: answer accuracy, citation coverage, freshness, cost per task.

8. Run a canary of 100 queries, compare to your baseline, then scale.

FAQ

• How does MCP reduce hallucinations? It grounds answers in fresh, cited web context with confidence signals and enforced schemas.

• Search or Web Search Agent? Use Search when your agent does its own reasoning and needs results fast. Use a Web Search Agent when the task needs multi-step research, citations, and a schema.

• Can I deliver to Databricks or Snowflake? Yes, through the API or direct delivery to your warehouse or object storage.

Key resources

• Nimble Agent Setup

• Nimble Platform, Products, and APIs

• Web Search Agents docs

• Search docs

• Trust Center