# Tools and credentials

> Manage the APIs your agents call mid-conversation, and the credentials they send, from your own pipeline.

A **tool** is a request an agent can make in the middle of a conversation: look up an order, book a
table, check a balance. An **MCP server** gives an agent every tool a remote server offers. Both can
send a **credential** from the vault. All three can be managed through the API, so the pipeline
that deploys your agents ([Agents as code](/guides/agents-as-code)) can put their tools and
credentials in place too.

## The keys they need

- **Change tools** (`tools:write`) reads, makes, changes and deletes tools and MCP servers. It is
  ticked on its own, never part of a starting point: a tool decides where an agent sends what a
  caller tells it.
- **Write tool credentials** (`vault:write`) adds, rotates and deletes credentials. **Only an owner
  can make a key with it**, because only owners manage the vault in the console. The key must reach
  every project, since a credential belongs to the organization and is given to projects.

Both need a **live** key to change anything. A test key can read tools and MCP servers, and
changes nothing. A key limited to some agents cannot change tools, because a tool belongs to its
whole project.

## Add a credential

```sh
node aigently.mjs vault-secrets create --name "Orders API" --secret "$ORDERS_API_TOKEN" \
  --project-ids 0b1c2d3e-…
```

The answer has the credential's `id`, its name, its last four characters and the projects that may
use it. **Its value is never sent back** by anything: not by this answer, the list, the console, or
the audit log. Send a new `secret` with `PATCH /v1/vault/secrets/{id}` to rotate it; tools send the
new value from their next request. The list shows `status: revoked` for a credential an owner
revoked in the console, which cannot be changed again (`credential_revoked`).

Only tool credentials are here. A model provider's key decides who bills your organization, so it
stays in the console.

## Create a tool

`POST /v1/tools` takes the tool's `name`, the `description` its model reads, the JSON Schema of its
`parameters`, and the `http` request it makes:

```json
{
  "method": "GET",
  "url": "https://orders.aigently.ai/v1/orders/{order_id}",
  "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-…" }
}
```

The same rules as the console apply:

- **The address must be public.** An address on a private network is refused with
  `validation_failed`.
- **A credential must be a tool credential given to the tool's project.** Otherwise the request
  is refused with `validation_failed`.
- **A credential goes only where it already goes.** The first tool that sends it decides the host
  it may be sent to (`bound_hosts` on the credential). An API key can use it on that host as often
  as you like, but can never send it anywhere new. That request is refused with
  `permission_denied`. An owner or an admin can send it somewhere new by saving the change in the
  console. So a leaked key cannot point your credential at a server of its own.

Then give the tool to agents by name, in `references.tools` of their definitions.

## MCP servers

`POST /v1/mcp-servers` adds a remote MCP server to a project, by `url`, with an optional
`auth_key_id`, `allowed_tools` and `timeout_ms`. It follows the same address and credential rules
as a tool. Give it to agents by name, in `references.mcp_servers` of their definitions. A
deployment that does not run MCP servers answers `feature_disabled`.

## What reads hide, and what is kept

A tool's header values and an MCP server's path and query are shown as `••••` when you read
them, because they often are the credential. Keep secrets in the vault and name them, rather than in
a header.

**Sending a hidden value back keeps what is stored.** You can read a tool, change its
description or add a header, and send the whole `http` back. Every value still reading `••••` keeps
its stored value. A `••••` with nothing stored behind it, in a new tool or a new header, is refused
rather than sent to your API as a credential.

## Changes reach agents at once

A changed or deleted tool, server or credential reaches every agent that has it on its next turn.
`agent_count` on a tool says how many agents that is. Each change is in the
[audit log](/guides/audit-log) under the key that made it, with the console's own event names.