Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.powabase.ai/llms.txt

Use this file to discover all available pages before exploring further.

Beyond basic tools and knowledge bases, agents support three powerful 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)
1

Add an MCP server

Connect an external MCP server to your agent. The agent discovers and calls tools exposed by the MCP server over SSE transport 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/sse",
        "transport": "sse",
        "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")
Response:
{
  "id": "mcp-uuid",
  "name": "GitHub Tools",
  "url": "https://mcp.example.com/github/sse",
  "transport": "sse",
  "created_at": "2026-01-01T00:00:00Z"
}
2

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
Hook events: PreToolUse (before tool execution), PostToolUse (after tool execution). Use the optional matcher field to target a specific tool by name.
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']}")
3

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="")
4

Approve a pending tool call

When an approval_requested event pauses a run, call the approve endpoint to allow execution to 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 choose an alternative approach or respond to the user.
# 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()}")

​
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.