agentport-overview

AgentPort: overview

What is AgentPort?

AgentPort is a tool gateway that sits between AI agents and external services. Instead of connecting directly to GitHub, PostHog, Stripe, or other APIs, agents connect to a single AgentPort endpoint. AgentPort then proxies those calls to the right upstream service.

This matters for a few reasons:

• Centralised auth. Credentials for every integration live in one place. The agent never touches raw API keys.
• Policy enforcement. Administrators can require human approval before certain tools execute — by integration, by tool name, or by specific argument values.
• Audit log. Every tool call is recorded: who called it, with what arguments, what the result was, and whether it needed approval.
• One connection for everything. Add or remove integrations without touching agent configuration. The tool list updates automatically.

Two ways to interact

There are two ways an agent can drive AgentPort. Pick the one that matches how you're wired in:

• Native MCP client. You connect directly to the AgentPort MCP endpoint and see every integration's tools through the MCP protocol. This is the right path if your runtime already speaks MCP (Claude Desktop, Cursor, any MCP-capable framework). See the agentport-mcp skill.
• CLI (ap). You shell out to the ap command-line tool to list installed integrations, inspect tool signatures, and execute tool calls. This is the right path when you're a code-running agent without a native MCP client. See the agentport-cli skill.

Whichever path you take, the rules below apply identically.

How tool calls resolve

Every tool call resolves to one of three outcomes:

1. Allowed — the tool executes immediately and you get the result.
2. Approval required — the tool is gated by a human approval policy. Execution is blocked until a human approves.
3. Denied — the tool is blocked unconditionally by policy. The call will never succeed regardless of approval.

Handling approval-required responses

When a tool call requires approval, AgentPort returns an approval URL. The exact shape differs by interface (see the MCP and CLI skills), but the response always contains a link of the form https://<agentport>/approve/<request-id>.

What you must do

Stop and ask your human. Do not retry the tool call, do not attempt workarounds, do not call a different tool to achieve the same outcome. The approval gate exists because a human decided this action requires oversight.

Share the approval URL with the human in full. A good message looks like:

I need to call github create_issue but it requires your approval first. Please review and approve (or deny) the request here: https://agentport.example.com/approve/a1b2c3d4-… Once you've approved it, let me know and I'll continue.

After the human approves, retry the exact same tool call with the exact same arguments. AgentPort will recognise the approval and execute it.

If the human denies the request, stop. Do not attempt to achieve the same outcome by another means.

What to expect during normal operation

• Tool lists may change as integrations are added or removed by administrators. If a tool you previously used is missing, it may have been uninstalled.
• OAuth-authenticated integrations may occasionally need token refresh. If a tool call fails with an auth error, try once more — AgentPort will attempt a refresh automatically.
• All tool calls are logged. Every action you take through AgentPort is recorded and auditable.