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

# Connectors and tools

> Browse and declare connectors, authorise a deployed agent with vio connect, and set up the built-in tools — including the Tavily key web_search needs.

<Note>
  Needs `vio` **1.0.0** or later. Check with `vio --version`.
</Note>

## Browse the connector catalogue

```bash theme={"dark"}
vio connectors [term]
```

Lists the connectors a `.vio` bundle can declare — no sign-in needed. `term` filters by
name; narrow further with `--category <category>`, `--auth <dcr | pre-registered | none>`
or `--verified`. `--json` prints the machine-readable form.

`vio connectors <id>` shows one connector's detail, including the tool names it exposes —
the first place to look when you need a tool's exact name (see below).

## Declare a connector in `agent.vio`

A connector is a `requires[]` entry:

```yaml theme={"dark"}
requires:
  - connector: https://mcp.example.com/v1/mcp
    scopes: []
    auth: oauth
    kind: connector
    tools:
      - search_docs
      - read_doc
```

`connector` is the MCP server URL, `auth` is `oauth` or `api_key`, and `tools` is the
explicit list of tool names this dependency may call — never a wildcard.

**The moment the agent has any skill, `requires[].tools` stops being what grants a tool.**
Each skill's own `allowed-tools` frontmatter becomes the only source of what that skill can
call — a space-separated line, not a YAML list:

```
---
name: research-helper
allowed-tools: search_docs read_doc
---
```

`requires[].tools` still has to list every tool the bundle uses (it is what `vio validate`
checks connector reachability against), but for a 0-skill agent it is also the entire
grant; for an agent with one or more skills, a tool absent from a skill's `allowed-tools`
is unavailable to it even if `requires` lists it. See [Use `vio` with AI coding
agents](/cli/ai-agents) and the Space's own `VIO-AGENTS.md` (`vio docs agents`) for the
full worked example.

### Where the real tool names come from

`requires[].tools` and `allowed-tools` both need a tool's *exact* name — never a guess, and
never the connector's id. Work through these in order:

1. **`vio connectors <id>`** — if it lists the connector's tools, use them exactly as
   printed.
2. **Your own coding agent's MCP session**, if you have the same service connected there —
   it shows tools as `mcp__<server>__<tool>`; the part after the server prefix is the exact
   name.
3. **The provider's own MCP server documentation.**
4. **Ask a human.** Never invent one.

A name the runner can't match is silently skipped at run time — no error anywhere — so
after the first deploy and `vio connect`, run the agent once and check its output or
`vio logs` to confirm the tool was actually called. `allowed-tools` also only ever takes
individual tool names: a connector-level reference like `atlassian` or `atlassian__*` does
not resolve.

## `vio connect`

If the agent uses connectors that need sign-in (for example Notion or Google Workspace),
authorise them after deploying. `vio connect` is subcommand-only — there is no
`/connect` in the shell:

```bash theme={"dark"}
vio connect <deployment id>
```

Run it from the Space, or pass the bundle as a second argument:
`vio connect <deployment id> ./agent.vio`. The id can be the full id, a unique prefix of at
least six characters, or the deployment's exact name.

`vio` runs each connector's consent in your browser, one at a time, then pushes all of the
agent's credentials — connector tokens, the provider key or Tavily key, whichever apply —
to it in one write. Run the same command again to re-authorise. `--no-browser` prints each
authorisation URL instead of opening it.

<Note>
  `vio connect` needs something to push. On a bundle with no OAuth connector it refuses with
  "This bundle declares no OAuth connectors, so there is nothing to authorise" — unless the
  bundle uses `web_search`, in which case (`vio` **1.0.1** or later) it skips consent and
  pushes the [Tavily key](#tavily-web_search) on its own.
</Note>

### Connectors that need your own OAuth app

Most connectors register themselves. Some — Google Workspace, GitHub, Slack, HubSpot and
Asana among them — need an OAuth application you create with the provider. For those,
`vio connect`:

1. **Shows the redirect URI first**, before it asks for anything:

   ```
   This connector requires your own OAuth application.
   Add this exact URL to the provider's Authorized redirect URIs:
   https://api.viorant.ai/oauth/connector/callback
   ```

   Add it to your OAuth app, and save the app.
2. **Asks for the app's client id and secret.** The secret is not echoed. Leave it empty
   for a public client.
3. **Offers to save them**, once the authorisation has succeeded:
   `Save to .vio/.env.connectors? [Y/n]`. Saved credentials are read from there on every
   later run, so you enter them once.

They are stored as two lines in `.vio/.env.connectors`, named for the app:

```bash title=".vio/.env.connectors" theme={"dark"}
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...
```

Every Google Workspace connector shares the `GOOGLE_` pair. The others use `GITHUB_`,
`SLACK_`, `HUBSPOT_` or `ASANA_`, and any other host is named after the host itself —
`mcp.example.com` reads `MCP_EXAMPLE_COM_OAUTH_CLIENT_ID`. You can also write the lines
yourself before running `vio connect`.

Without a terminal to ask on, `vio connect` can't prompt: it prints the redirect URI and
stops. Add the two lines to `.vio/.env.connectors`, then run it again.

<Warning>
  OAuth app credentials belong in `.vio/.env.connectors` only. Never put a client id or
  secret in `agent.vio` — the bundle travels with the agent.
</Warning>

### Is the agent ready?

`vio connect` reports what the agent says after the push, not what it hopes:

* `✔ Connectors authorised — the agent is ready` — the agent is serving with nothing
  pending.
* `✔ Credentials pushed. The agent still reports <state>` — the push worked and the agent
  hasn't picked the credentials up yet. It lists what is still pending, and reloads them
  on its next run or within about a minute. Check with `vio show <id>`.

### Before you run it

* For a BYOK agent, have the same provider key you deployed with — in the Space, or the
  same `--env-file`. The push replaces every credential the agent holds, including its
  provider key, and a key of the wrong kind is refused before any consent.
* A [credits](/cli/deploy#viorant-credits) agent needs no provider key for `vio connect`
  either, and `vio connect` never pushes one to it — even if a key is set in the Space or
  the `--env-file`.
* The bundle must be the one you deployed. If its digest differs, nothing happens.
* Cancelling any consent pushes nothing; the agent keeps what it had.
* Port `47219` on `127.0.0.1` must be free while it runs.

## Built-in tools on a deployed agent

Three tools need no connector — they need no external MCP server, so nothing goes in
`requires[]`. They're granted the same way a connector tool is: by exact name, in a skill's
`allowed-tools`.

| Tool | What it needs |
| - | - |
| `web_fetch` | Nothing. |
| `current_time` | Nothing. |
| `web_search` | A Tavily API key. |

Unlike a connector's tools, these three names are fixed — there is nothing to look up in
`vio connectors` or an MCP session for them. Use `web_fetch`, `current_time` and
`web_search` exactly as written.

### Tavily (`web_search`)

`web_search` is powered by [Tavily](https://tavily.com), and it always needs **your own**
Tavily key — on Viorant credits too. Viorant credits pay for the model; they do not pay for
search.

<Steps>
  <Step title="Get a key">
    Sign up at [tavily.com](https://tavily.com) and copy your API key — it starts with
    `tvly-`.
  </Step>

  <Step title="Add it to the Space">
    Put it in `.vio/.env.connectors`:

    ```bash title=".vio/.env.connectors" theme={"dark"}
    VIORANT_RUNNER_SEARCH_API_KEY=tvly-...
    ```
  </Step>

  <Step title="Deploy">
    `vio deploy` reads it and sends it to the agent as a **sealed secret** — it is never
    written into the bundle, and no `.vio` file ever carries it.
  </Step>
</Steps>

Tavily bills you directly for usage; it is not metered through your Viorant wallet.

**Adding or rotating the key on an already-deployed agent** depends on what else the agent
declares:

* **The agent also has an OAuth connector.** `vio connect <deployment id>` pushes the whole
  credentials document on every run, Tavily key included — update
  `.vio/.env.connectors` and run `vio connect <deployment id>` again.
* **Tavily is the agent's only external dependency.** With `vio` **1.0.1** or later, the
  same command works: update `.vio/.env.connectors` and run `vio connect <deployment id>`.
  There is no consent step — it pushes the key and reports whether the agent is ready. If
  no key is set, it refuses and pushes nothing.

  On `vio` 1.0.0, `vio connect` refuses a bundle with no OAuth connector, so the only way to
  add the key there is to stop the agent and deploy again (a new id, URL and run key) — or
  run `vio update` first.

`vio redeploy` never sets or rotates a key: it replaces the running bundle only and does not
read `.vio/.env.connectors`.

Without a key, every call to `web_search` fails — the run itself still starts and the
agent still reports ready; only that one tool is unavailable. `vio show` does not flag the
missing key, so if a search-using agent's answers show no web results, check
`.vio/.env.connectors` first.

## Next

* [Deploy an agent](/cli/deploy) — credits vs BYOK, and calling the deployed agent.
* [Manage deployments](/cli/manage) — list, runs, logs, redeploy and stop.