> ## 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.

# Nimble Agent Setup

> 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:

```bash theme={"system"}
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:

| Result                                                                    | Go to                                          |
| ------------------------------------------------------------------------- | ---------------------------------------------- |
| Either probe returns data                                                 | Step 5. Setup is done, do not install anything |
| A Nimble tool is listed but returns an auth error or an authorization URL | Step 3                                         |
| `nimble` exists but the probe fails on credentials                        | Fallback, then Step 4                          |
| Neither surface exists                                                    | Step 2                                         |

## 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:

|                       | MCP server                                                      | Nimble CLI                                                               |
| --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Authentication        | OAuth in the browser, nothing to store                          | API key only. No `login` command, so no OAuth                            |
| Where results land    | Through your context window                                     | A file or a pipe, your choice                                            |
| Cost of large results | Every token is charged to context                               | Write to disk and read what you need                                     |
| Product coverage      | Search, Extract, Extract Template, Map, Crawl, Web Search Agent | All of those, plus SERP, Media, Domain Knowledge, and Extract Jobs       |
| Best for              | Ordinary tool calls, and any host without a terminal            | Bulk crawls, whole-site extractions, and the products MCP does not carry |

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:

```bash theme={"system"}
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.

| Host                               | Command                                                                                                                                                                       |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code                        | `claude plugin marketplace add Nimbleway/agent-skills && claude plugin install nimble@nimble-plugin-marketplace`                                                              |
| Claude Cowork, claude.ai           | Install **Nimble** from the [plugin directory](https://claude.ai/directory/plugins/nimble%40knowledge-work-plugins)                                                           |
| Cortex Code                        | `cortex mcp add nimble https://mcp.nimbleway.com/mcp --transport http`                                                                                                        |
| Cursor, VS Code, other MCP clients | Add the config below, then `npx skills add Nimbleway/agent-skills -a <host>`                                                                                                  |
| Codex Desktop                      | Open **Plugins → Add → Add a marketplace**, add `https://github.com/Nimbleway/agent-skills.git`, install **Nimble**, approve OAuth, then call it in a new task with `@nimble` |
| Codex CLI                          | Add the Codex config below, then `npx skills add Nimbleway/agent-skills -a codex`                                                                                             |

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:

```json theme={"system"}
{
  "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`:

```toml theme={"system"}
[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](https://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:

```bash theme={"system"}
nimble search --query "nimble web data platform" --max-results 3
```

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

| Product          | Returns                                          |
| ---------------- | ------------------------------------------------ |
| Search           | Ranked web results across engines                |
| Extract          | Clean content from one URL, rendered when needed |
| Map              | Every URL on a site                              |
| Crawl            | Many pages, with path filters                    |
| Extract Template | Structured fields from supported sites           |
| Web Search Agent | Multi-step research with citations               |

## 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:

```bash theme={"system"}
[ -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](https://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](https://nimbleway.com/auth.md).

## 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](https://docs.nimbleway.com), with a machine index at [docs.nimbleway.com/llms.txt](https://docs.nimbleway.com/llms.txt).