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

# Use fetchbean as a Model Context Protocol MCP server

> Connect any MCP-compatible agent to fetchbean's hosted server and give it every tool in the catalog through four meta-tools — discover, describe, run, and request.

The Model Context Protocol (MCP) is an open standard that lets AI agents connect to external tools through a uniform interface. fetchbean hosts an MCP server at `https://api.fetchbean.com/mcp`, so any MCP-compatible agent gets the entire fetchbean catalog — web search, page reads, weather, and every connected provider — over a single connection.

## Four meta-tools, not hundreds

The catalog is large and grows constantly, so the server does **not** enumerate every capability as its own MCP tool. It exposes exactly four meta-tools. An agent finds a tool by task, then runs it:

<CardGroup cols={2}>
  <Card title="discover" icon="magnifying-glass">
    Find the right tool for a task. Returns ranked tools, each with its `provider`, `endpoint`, a terse params list, and whether a connected account is needed. Always call this first.
  </Card>

  <Card title="describe" icon="list-check">
    Get the full input JSON Schema, an example call, cost, and connection info for one tool. Call it before `run` when you are unsure of the arguments.
  </Card>

  <Card title="run" icon="play">
    Execute a tool by its `provider` and `endpoint`, passing input that matches its schema. Spends prepaid credits.
  </Card>

  <Card title="request" icon="inbox">
    Log a request for a tool fetchbean does not have yet, at the moment you needed it. Free, and attributed to your org.
  </Card>
</CardGroup>

This mirrors the HTTP surface exactly — `discover` and `describe` map to `GET /discover`, and `run` maps to `POST /v1/run`.

## Configuration

Add the server to your agent's MCP configuration. It speaks Streamable HTTP and is stateless, so there is no local process to run:

```json theme={null}
{
  "mcpServers": {
    "fetchbean": {
      "url": "https://api.fetchbean.com/mcp",
      "headers": { "X-API-Key": "fb_your_key_here" }
    }
  }
}
```

Your key goes in the `X-API-Key` header, configured once — the agent never handles it per call. Create a key under **API Keys** in the [dashboard](https://fetchbean.com/app).

## What needs a key

Discovery is open; execution is not.

| Tool       | Key required | Billing                                                  |
| ---------- | ------------ | -------------------------------------------------------- |
| `discover` | no           | free                                                     |
| `describe` | no           | free                                                     |
| `run`      | yes          | spends credits; provider failures and timeouts bill zero |
| `request`  | yes          | free                                                     |

Because `discover` and `describe` are open, an agent can explore the catalog and see exactly what a call would cost before it commits to one.

## A typical exchange

An agent that needs current web results works through the tools in order:

<Steps>
  <Step title="discover">
    Call `discover` with `q: "web search"`. The response ranks matching tools and returns the `provider` and `endpoint` for each.
  </Step>

  <Step title="describe (optional)">
    If the arguments aren't obvious from `discover`, call `describe` with that `provider` and `endpoint` to get the full input schema and an example.
  </Step>

  <Step title="run">
    Call `run` with the `provider`, `endpoint`, and an `input` object matching the schema. You get the tool's normalized JSON back.
  </Step>
</Steps>

<Warning>
  Read tools fetch; write tools change state in the connected service. `run` will execute either, so confirm intent before running a write.
</Warning>

## Providers that need your own account

Some providers act on your account rather than on credentials fetchbean manages. `discover` flags these in its results, and `describe` names the provider to connect. Connect it once from the [dashboard](https://fetchbean.com/app?tab=connections) and every tool for that provider becomes callable through `run` with no change to your agent. See [Connections](/connections).

A `run` against an unconnected provider fails with `credential_required` and is billed zero.

## Asking for what isn't there

When an agent needs a tool the catalog doesn't have, `request` records it at the point of need instead of failing silently. `need` is the public-safe ask; anything proprietary belongs in `context`, which only the fetchbean team can see. Requests default to private — set `visibility: "public"` to add one to the public board and collect votes.

<Tip>
  Inspect the exact tool definitions the server serves, without a key, at `GET https://api.fetchbean.com/mcp/tools`. It returns the same four definitions the hosted endpoint uses, so a local bridge can never drift from it.
</Tip>