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

# MCP

> Give your agent access to Locus tools, Recipes, and Workflows through one connection.

Locus MCP lets your agent find the right tool, check its price, and use it with
your Locus balance. It brings search, research, enrichment, and other paid APIs
into the agent you already use, without separate provider accounts.

MCP, the Model Context Protocol, is how an agent discovers and calls tools.
You describe the outcome; your agent uses Locus to get the data or complete
the task.

## Connect once

Add this Streamable HTTP server to your agent and complete browser sign-in:

```text title="MCP server URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp
```

The [Locus plugin](/locus-pro/individual/connect-agents#install-the-locus-plugin)
includes this connection plus skills for setup, tool use, and Workflows.
For client-specific instructions, see [Connect an agent](/locus-pro/individual/connect-agents).

Then try:

```text title="Try this prompt" wrap theme={null}
Use Locus to research three competitors for my project. Read their current pricing pages, compare their features, and link to the sources.
```

Your agent can discover tools, request your approval for disabled ones, and
read results back into the conversation. Paid calls use your credit balance.
Your tool permissions and spending limits still apply.

## Choose a mode

Both modes can use the same permitted catalog through `execute`. The difference
is how many tool definitions your agent loads and the names it sees.

* **Standard (default):** Descriptive tool names, available Recipes, and selected
  or pinned endpoints. Use it to make Recipes and frequent tools directly accessible.
* **Compact:** Short discovery and execution names, account helpers, and available
  Workflow tools. Use it to load fewer tool definitions into your agent's context.

The plugin and the plain MCP URL use standard mode. To choose compact mode,
change the URL in your client's MCP configuration to:

```text title="Compact mode URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp?surface=compact
```

Refresh the connection or start a new session after changing it. Keep one
connection per client; you do not need a second server entry.

<Note>
  `?surface=compact` reduces the tool list and removes whitespace from JSON
  result text. `?compact=1` only changes result formatting. Both preserve the
  structured result.
</Note>

## How your agent uses Locus

1. **Find a tool.** Search by the outcome you need, or browse categories and packs.
2. **Check the inputs and price.** Read the endpoint description; request an exact
   quote or hard spending ceiling when needed.
3. **Run it.** Call the enabled endpoint and use the returned data. Large results
   can be read in chunks without repeating the paid call.

Search returns enabled tools by default. Your agent can include disabled tools
and request an approval link for one you need. You decide whether to enable it.

For repeatable work, your agent can build, test, save, and run a
[Workflow](/locus-pro/individual/workflows) through the same connection.

## All tools

The tables below cover Locus's built-in tools. Your client's live tool list
reflects your connection permissions, available features, and selected mode.
Provider-specific tools are discovered from the catalog as described below.

### Find and use tools

Where names differ, the compact name appears second.

| Tool (standard / compact)        | Purpose                                                      |
| -------------------------------- | ------------------------------------------------------------ |
| `search_apis` / `search`         | Find APIs and Recipes with prices, inputs, and access status |
| `describe_api` / `describe`      | Read an endpoint's inputs, example, output format, and price |
| `estimate_cost` / `estimate`     | Quote a call, optionally with a hard credit ceiling          |
| `execute`                        | Call an enabled API or Recipe; paid calls charge credits     |
| `get_call_result` / `get_result` | Read a stored result without rerunning the paid call         |
| `list_tool_groups`               | Browse categories and curated packs                          |
| `get_locus_guide`                | Retrieve setup, usage, or Workflow guides                    |
| `request_tool_access`            | Create a human approval link for a disabled tool             |
| `get_balance`                    | Check the balance available to the connection                |

### Workflows

These names are the same in both modes. Workflow authoring and execution
require an execution-enabled connection.

| Tool                  | Purpose                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `workflow_definition` | List, create, inspect, update, clone, archive, or save a Workflow                          |
| `workflow_validate`   | Check source code or run isolated tests without network access                             |
| `workflow_run`        | Start a pilot or production run of a saved version with a hard credit ceiling              |
| `workflow_runs`       | List runs, read status and stored results, cancel further calls, or resume an eligible run |

### Additional standard tools

| Tool                   | Purpose                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `list_apis`            | Browse a page of enabled endpoints and prices; omitted from the advertised list when more than 20 endpoints are available |
| `cancel_cost_approval` | Cancel an unused executable quote                                                                                         |
| `pin_endpoint`         | Add or remove a saved endpoint pin when pinning is available; requires permission to manage pins                          |

These tools are not advertised in compact mode. Their original names remain
callable when your connection is permitted to use them.

### Direct Recipe tools

Standard mode also lists these [Recipes](/locus-pro/individual/recipes) when
they are available to your connection. In compact mode, find the Recipe with
`search`, then call its endpoint through `execute`.

| Tool                | Purpose                                               |
| ------------------- | ----------------------------------------------------- |
| `router_web_search` | Search the web across providers                       |
| `web_research`      | Research a question and return a source-backed answer |
| `web_extract`       | Extract content from specific URLs                    |
| `gtm_enrich`        | Enrich a person or company with field-level sources   |
| `travel_flights`    | Search flights across providers                       |

Search returns the endpoint slug and inputs to use with `execute`.

### Provider-specific tools

Locus does not load the entire catalog as individual MCP tools. Your agent
discovers endpoints through search and calls them with `execute`.

In standard mode, you can expose frequently used endpoints as direct tools
with their own input schemas. Append `?tool=provider/endpoint` to the MCP URL,
using an exact slug returned by search. Repeat `tool` to select more, up to 20.
Saved pins can also expose endpoints across your workspace's connections.

Direct tool names usually follow `provider_endpoint`. Use the name returned
by Locus rather than constructing it yourself. Enabling or pinning a tool
does not override the connection's access or spending limits.

<AccordionGroup>
  <Accordion title="Permissions and service credentials">
    Browser OAuth is the usual connection for Locus Pro. Read-only consent
    (`mcp:read`) allows discovery, balance checks, estimates, and stored-result
    reads. Paid calls and Workflow operations require `mcp:execute`.

    Locus Pro Enterprise also supports scoped Agent Connections, server keys,
    and end-user tokens. End-user JWTs cannot use Workflows. Connections bound
    to an end user cannot request workspace tool access. Sandbox keys cannot use MCP.

    Saved pin changes require an owner or admin, or a server key with
    `catalog:write`. The first pin requires acknowledgement that its schema
    will use context on each connection.

    See [Enterprise connection setup](/locus-pro/connect-agents#enterprise-service-credentials)
    for credential configuration.
  </Accordion>

  <Accordion title="Resources and prompts">
    Clients that support MCP resources can read the catalog (`locus://catalog`),
    balance (`locus://balance`), Recipe index (`locus://recipes`), and GTM guide
    (`locus://recipes/gtm-enrich-record`). Resource templates provide catalog
    pages and stored call results.

    The server also offers `getting-started`, `find-and-call-api`, and
    `enrich-gtm-record` prompts. Read-only connections receive the getting-started
    prompt.
  </Accordion>
</AccordionGroup>

For detailed agent instructions, use the
[MCP reference](https://paywithlocus.com/agent/mcp.md) or ask your agent to call
`get_locus_guide`.