Advanced Agent Configuration

Beyond basic tools and knowledge bases, agents take three further configuration options: MCP (Model Context Protocol) servers for external tool integrations, hooks for triggering webhooks on agent lifecycle events, and an approval flow that pauses execution until a human approves sensitive tool calls. This guide walks through each one.

Prerequisites:

An agent created (see Build an Agent guide)

Add an MCP server

Connect an external MCP server to your agent. The agent discovers and calls tools exposed by the MCP server over HTTP transport (default; SSE is also accepted) during runs.Endpoint: POST /api/agents/{id}/mcp-servers

The agent connects to the MCP server at the start of each run to discover available tools. Tools are then available alongside builtin tools and knowledge base search.

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/mcp-servers",
    headers=headers,
    json={
        "name": "GitHub Tools",
        "url": "https://mcp.example.com/github/mcp",
        "transport": "http",
        "headers": {
            "Authorization": "Bearer ghp_your_token_here",
        },
    },
)
mcp_server = response.json()
print(f"MCP server added: {mcp_server['id']}")
print(f"Available tools will be discovered at runtime")

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "GitHub Tools",
    url: "https://mcp.example.com/github/mcp",
    transport: "http",
    headers: {
      Authorization: "Bearer ghp_your_token_here",
    },
  }),
});
const mcpServer = await response.json();
console.log("MCP server added:", mcpServer.id);

curl -X POST '{BASE_URL}/api/agents/{agent_id}/mcp-servers' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Tools",
    "url": "https://mcp.example.com/github/mcp",
    "transport": "http",
    "headers": {
      "Authorization": "Bearer ghp_your_token_here"
    }
  }'

Response:

{
  "id": "mcp-uuid",
  "agent_id": "agent-uuid",
  "name": "GitHub Tools",
  "url": "https://mcp.example.com/github/mcp",
  "transport": "http",
  "headers": { "Authorization": "Bearer ..." },
  "config": {},
  "enabled": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Configure a webhook hook

Add an HTTP webhook hook that fires before each tool call. Use hooks to log tool usage, enforce policies, or notify external systems.Endpoint: POST /api/agents/{id}/hooks

This example uses PreToolUse, but hooks fire at six lifecycle events (OnRunStart, PreToolUse, OnDelegation, PostToolUse, PreResponse, OnRunComplete) and come in three types (http, rule, approval). Use the optional matcher field to target a specific tool by name. See Hooks & Middleware for the full event semantics and the webhook request/response contract.

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/hooks",
    headers=headers,
    json={
        "event": "PreToolUse",
        "type": "http",
        "config": {
            "url": "https://your-app.com/webhooks/tool-calls",
        },
    },
)
hook = response.json()
print(f"Hook created: {hook['id']}")
print(f"Event: {hook['event']}, Type: {hook['type']}")

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/hooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    event: "PreToolUse",
    type: "http",
    config: {
      url: "https://your-app.com/webhooks/tool-calls",
    },
  }),
});
const hook = await response.json();
console.log("Hook created:", hook.id);
console.log("Event:", hook.event, "Type:", hook.type);

curl -X POST '{BASE_URL}/api/agents/{agent_id}/hooks' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "PreToolUse",
    "type": "http",
    "config": {"url": "https://your-app.com/webhooks/tool-calls"}
  }'

Enable approval flow

Add an approval hook to the agent. When a tool call matches, the run pauses and emits an approval_requested SSE event. The run waits until you approve or reject via the API.Endpoint: POST /api/agents/{id}/hooks

Set matcher to a specific tool name to only require approval for that tool, or omit matcher to require approval for all tool calls.

# Add an approval hook — pauses on database_query calls
response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/hooks",
    headers=headers,
    json={
        "event": "PreToolUse",
        "type": "approval",
        "matcher": "database_query",
        "config": {"message": "Approve this database query?"},
    },
)
print(f"Approval hook added: {response.json()['id']}")

# Stream a run — watch for approval_requested events
response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={"message": "Delete all inactive users from the database"},
    stream=True,
)

import json

for line in response.iter_lines():
    if not line:
        continue
    text = line.decode("utf-8")
    if not text.startswith("data: "):
        continue
    event = json.loads(text[6:])

    if event["event"] == "approval_requested":
        print(f"Approval needed for: {event['tool_name']}")
        print(f"Input: {json.dumps(event.get('tool_input', {}), indent=2)}")
        print(f"Run ID: {event['run_id']}")
        # The stream pauses here — approve or reject via the API
        break

    elif event["event"] == "chunk":
        print(event["content"], end="")

// Add an approval hook — pauses on database_query calls
await fetch(`${BASE_URL}/api/agents/${agentId}/hooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    event: "PreToolUse",
    type: "approval",
    matcher: "database_query",
    config: { message: "Approve this database query?" },
  }),
});

// Stream a run and watch for approval_requested events
const response = await fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "Delete all inactive users from the database" }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const event = JSON.parse(line.slice(6));

    if (event.event === "approval_requested") {
      console.log(`Approval needed for: ${event.tool_name}`);
      console.log("Input:", JSON.stringify(event.tool_input ?? {}, null, 2));
      console.log(`Run ID: ${event.run_id}`);
      // Stream pauses here — approve or reject via the API
      break;
    }

    if (event.event === "chunk") {
      process.stdout.write(event.content);
    }
  }
}

# Add an approval hook for database_query
curl -X POST '{BASE_URL}/api/agents/{agent_id}/hooks' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "PreToolUse",
    "type": "approval",
    "matcher": "database_query",
    "config": {"message": "Approve this database query?"}
  }'

# Stream a run — look for approval_requested events
curl -N -X POST '{BASE_URL}/api/agents/{agent_id}/run/stream' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"message": "Delete all inactive users from the database"}'

Approve a pending tool call

When an approval_requested event pauses a run, call the approve endpoint to let execution continue, or reject to skip the tool call.Endpoint: POST /api/agents/runs/{run_id}/approve

After approval, the SSE stream resumes and the tool executes normally. After rejection, the agent skips the tool call and may try a different approach or respond to the user directly.

# Approve the pending tool call
response = requests.post(
    f"{BASE_URL}/api/agents/runs/{run_id}/approve",
    headers=headers,
    json={"approved": True},
)
print(f"Approved: {response.json()}")

# Or reject
response = requests.post(
    f"{BASE_URL}/api/agents/runs/{run_id}/approve",
    headers=headers,
    json={"approved": False},
)
print(f"Rejected: {response.json()}")

// Approve the pending tool call
const approveRes = await fetch(
  `${BASE_URL}/api/agents/runs/${runId}/approve`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({ approved: true }),
  },
);
console.log("Approved:", await approveRes.json());

// Or reject
const rejectRes = await fetch(
  `${BASE_URL}/api/agents/runs/${runId}/approve`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({ approved: false }),
  },
);
console.log("Rejected:", await rejectRes.json());

# Approve
curl -X POST '{BASE_URL}/api/agents/runs/{run_id}/approve' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"approved": true}'

# Reject
curl -X POST '{BASE_URL}/api/agents/runs/{run_id}/approve' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"approved": false}'

What’s Next

Agents & Tools

Understand the full tool system including MCP, builtins, and custom tools.

Orchestration

Coordinate multiple agents working together.

Agents API Reference

Full endpoint documentation for agents.

​What’s Next

Agents & Tools

Orchestration

Agents API Reference

What’s Next