Tools and credentials

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

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:

{
  "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 under the key that made it, with the console's own event names.