Use this guide to connect an AI agent to Nimble for live web search, extraction, mapping, crawling, and structured extraction. The canonical machine-readable copy is docs.nimbleway.com/agents.md.

Documentation Index

Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt Use this file to discover all available pages before exploring further.

Connect an AI agent to Nimble for live web search, extraction, mapping, and crawling

You are an agent setting up Nimble for a user. Nimble gives you live web data: search, extract, map, crawl, and structured extraction.

Follow the steps in order. Do not skip ahead. Most hosts need no API key.

Step 1: Check what is already available

Two surfaces reach Nimble: the MCP server and the nimble CLI. Probe both before installing anything. Either one working means the user is already set up.

MCP. If your host lists any Nimble tool, call the read-only one:

nimble_agents_list

CLI. If you can run shell commands, check the binary and the key together:

command -v nimble && nimble --version && nimble agents list

nimble agents list is read-only and confirms both the install and the credential in one call. The CLI reads NIMBLE_API_KEY from the environment. It has no OAuth support, so without that variable it cannot authenticate.

Route on the result:

Step 2: Choose a surface, then install

Which surface

If you cannot run shell commands, use MCP. That is the only option.

If you can, both work, and they differ in ways that matter:

Default to MCP, because it needs no API key. Three exceptions:

• On Claude products, start with the plugin. It installs the MCP connector and the skills. The skills call the nimble CLI, which is a separate install: npm i -g @nimble-way/nimble-cli plus NIMBLE_API_KEY. Add the CLI only if you need one of the products below that MCP does not carry.

• If the task needs SERP, Media, Domain Knowledge, or Extract Jobs, install the CLI. The MCP server does not expose those, so MCP alone cannot do the job.

• If the task is bulk retrieval, say a crawl of a whole site, ask the user once whether to add the CLI. Name the reason in one sentence: large results are cheaper written to a file than passed through the context window. If they have no API key and do not want one, stay on MCP.

Do not install both without being asked. One working surface is enough.

Install the CLI

Only where a terminal is available:

npm i -g @nimble-way/nimble-cli

Then set NIMBLE_API_KEY, as described in the Fallback section, and go to Step 4. The CLI does not use OAuth, so skip Step 3.

Install the MCP server

Pick the row that matches your host.

The <host> value is your client name, for example cursor or codex. The skills teach you which Nimble product fits a given job. They are optional but recommended.

Manual MCP configuration

For any client that reads a standard MCP config file, add:

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

No Authorization header. The server advertises OAuth, and the first tool call starts the flow.

Cursor reads .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all projects.

Codex CLI

In Codex Desktop, install the packaged Nimble plugin instead. It bundles the skills and the MCP connection, and authenticates with OAuth, so none of the configuration below is needed.

Codex CLI authenticates the Nimble server with an API key rather than OAuth. Add to ~/.codex/config.toml, or a project-scoped .codex/config.toml:

[mcp_servers.nimble-mcp-server]
url = "https://mcp.nimbleway.com/mcp"
bearer_token_env_var = "NIMBLE_API_KEY"

Codex reads NIMBLE_API_KEY from the environment at runtime, so the key never enters the config file. If the variable is not set, follow the Fallback section below, then skip to Step 4.

Full per-client detail lives at docs.nimbleway.com/integrations/agent-skills/plugin-installation.

Step 3: Authorize

https://mcp.nimbleway.com/mcp runs OAuth 2.1 with PKCE. Authorization happens in the user's browser. No API key is created, pasted, or stored.

• Claude Code: run /mcp and follow the prompt

• Claude Cowork, claude.ai: open Customize → Connectors, find Nimble, click Connect

• Cortex Code: run cortex mcp start

• Codex Desktop: OAuth opens in the browser as soon as the plugin installs

• Other clients: the first tool call returns an authorization URL

The user approves the scopes and, if they have no Nimble account, creates one during that same login.

If a tool returns an authorization URL instead of data: present the URL exactly as given and stop. There is no step where the user pastes anything back to you. Wait for them to authorize, then return to Step 1 and probe again.

Never substitute a different tool while waiting. Do not fall back to a generic web fetch, a search tool, or curl. Those return different data and hide the setup failure from the user.

Step 4: Verify

Repeat the Step 1 probe for whichever surface you installed. Expect a successful response.

In Claude Code, claude mcp list also shows MCP state directly. Look for nimble marked ✓ Connected. A ! Needs authentication marker means Step 3 is incomplete.

Step 5: Run something

Confirm the setup with a real call.

Through MCP:

nimble_search with query "nimble web data platform"

Through the CLI:

nimble search --query "nimble web data platform" --max-results 3

Then tell the user Nimble is ready, and name what it now covers:

Fallback: API key

Use this only when your host cannot speak MCP or cannot complete OAuth. An API key is a long-lived secret, so OAuth is preferred wherever it works.

Check whether NIMBLE_API_KEY is already set, without printing its value:

[ -n "$NIMBLE_API_KEY" ] && echo set || echo missing

If it is set, use it without ever reading the value. Let the shell expand the variable and send it as a bearer token:

Authorization: Bearer $NIMBLE_API_KEY

Store the raw key. The Bearer prefix belongs in the header, not in the stored value.

If it is not set, ask the user to create a key at online.nimbleway.com/settings/api-keys and set it in their environment.

Never print the key, and never read it into your own context. Do not run printenv NIMBLE_API_KEY, echo $NIMBLE_API_KEY, or any equivalent. Do not write it to a file you commit or include it in output the user might share. Transcripts get pasted into issues and retained by hosts, so a key you print is a key you have leaked.

For the full credential path, including where to look for an existing key and how to handle errors, read nimbleway.com/auth.md.

Related guides

• Nimble for AI Agents: MCP and Browser Agents Technical Spec

• Production Quickstart and Reference Architectures for Agent Deployments

• Complete Nimble documentation index

Notes

• With a terminal available, prefer nimble over hand-written curl. It reads NIMBLE_API_KEY itself, and --transform pulls one field out of a response without a second parsing step.

• The full documentation is at docs.nimbleway.com, with a machine index at docs.nimbleway.com/llms.txt.