Connect an agent to tools

Connect a tool server to your project's MCP gateway, grant a tool to an agent, and call it with the agent's access token.

In this tutorial you connect a tool server to your project's MCP gateway, grant one of its tools to an agent, and call that tool with the agent's access token.

Each project has a gateway that speaks the Model Context Protocol (MCP), the protocol AI agents use to call tools. Your agents call tools through the gateway instead of holding each tool's credentials themselves.

https://acme.authfi.io/mcp

The gateway checks every call against what the agent was granted, and against any limit on the grant. It holds the tool's credential, so the credential never reaches the agent. It makes a call wait for a person when a rule says so, and it writes each call to the audit record with its decision and reason.

Before you begin

You need:

• An AuthFI project and its issuer, the project's URL. This tutorial uses https://acme.authfi.io.
• An agent, and an access token for it whose resource is the gateway. Give an AI agent an identity ends with exactly that token.
• A tool server that speaks MCP, and its URL. This tutorial uses a server with tools for support tickets.
• Permission to manage the MCP gateway in the AuthFI console.

export ACCESS_TOKEN=<the agent's access token>

curl https://acme.authfi.io/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{
  "name": "tickets.reply",
  "description": "Reply to a ticket",
  "inputSchema": { "type": "object" },
  "annotations": { "io.authfi/governance": "no_policy_restriction" }
}

curl https://acme.authfi.io/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "tickets.reply", "arguments": { "ticket": "4821", "text": "On it." } }
  }'

Check that it works

In the console, open Integrations > MCP Gateway and select the Tape tab. The tape lists each call with the columns When, Caller, Tool, Verdict, Why and Acted for.

Find the row whose Caller is your agent and whose Tool is tickets.reply. Its Verdict reads allowed. The gateway checked the call and forwarded it.

Troubleshooting

A denied call is an ordinary tool result with isError set, so the model reads it and can change course.

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "Denied by policy: agent:agt_7f3a9c21 is not granted payments.refund" }]
  }
}

A 401 points to where the agent signs in.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://acme.authfi.io/.well-known/oauth-protected-resource"

The document at that URL names the project as the authorization server for the gateway, as RFC 9728 describes.

{
  "resource": "https://acme.authfi.io/mcp",
  "authorization_servers": ["https://acme.authfi.io"]
}

Next steps