agentport-mcp

AgentPort: MCP interface

Read agentport-overview first. This skill covers what's specific to reaching AgentPort as a native MCP client.

Connecting

AgentPort exposes a single StreamableHTTP MCP endpoint at https://ap.skaldlabs.io/mcp for the Cloud version and a custom domain for self-hosted deploys. Point your MCP client at that URL. Authentication is handled at the MCP transport layer (OAuth or API key), and once you're connected, every installed integration's tools show up in the aggregated tools/list response.

You do not open a separate connection per integration. AgentPort fans out internally.

Tool naming

Tools are namespaced so that multiple integrations can expose tools with the same underlying name without colliding:

{integration}__{tool}

The separator is a double underscore. Examples:

• github__list_issues
• posthog__get_events
• stripe__create_charge
• resend__send_email

When you see a tool in the aggregated list, the prefix tells you which integration it belongs to. Use the exact name, underscores and all, when you call the tool.

Always explain the call with additional_info

AgentPort injects an extra optional property named additional_info (string) into every tool's inputSchema. It is not part of the upstream tool's real arguments and is not forwarded to the vendor — AgentPort strips it before proxying. It is stored in the audit log and shown to any human who reviews the call (especially on approval-gated tools). Include it on every call.

A good additional_info answers two questions for a reviewer who sees the call without your conversation context:

1. What are you trying to do at the level of intent — "refund the duplicate charge Alice flagged", not "call create_refund".
2. Why now — the reason this call is happening at this moment, especially when acting on someone's behalf.

One sentence is usually enough.

Make opaque IDs verifiable

Many tool arguments are vendor IDs that mean nothing on their own: cus_OaBc…, Gmail message IDs, PostHog dashboard IDs, Slack channel IDs, Stripe invoice IDs. A reviewer cannot safely approve a call whose target is only identified by a random-looking string.

When an argument is an opaque ID, make it verifiable inside additional_info:

• Include a human-readable label alongside the ID (name, email, subject, title).
• Paste a link the reviewer can click to confirm what the ID refers to, when a public URL exists. Examples:
  • Stripe customer cus_OaBc… → https://dashboard.stripe.com/customers/cus_OaBc…
  • PostHog dashboard 42 → https://us.posthog.com/dashboard/42
  • GitHub issue #417 in owner/repo → https://github.com/owner/repo/issues/417
  • Gmail message <id> → https://mail.google.com/mail/u/0/#inbox/<id>
• If you don't have a clean URL, at minimum name the thing in words: customer Alice Jordan (cus_OaBc…).

Do not fabricate URLs you aren't sure are valid — a wrong link is worse than none. If you can't confidently link the ID, describe it instead.

Example call arguments for stripe__create_refund:

{
  "charge": "ch_3ObC…",
  "additional_info": "Refunding the duplicate $49 charge for customer Alice Jordan (cus_OaBc…, https://dashboard.stripe.com/customers/cus_OaBc…) that she flagged in support ticket #812."
}

Approval-required responses

When a tool call is gated, AgentPort returns an MCP content block that contains the approval URL in plain text. It looks roughly like:

Approval required: https://agentport.example.com/approve/a1b2c3d4-…

Treat this as a stop condition. The overview skill describes what to do — share the URL with your human, wait for approval, then retry the exact same call with the exact same arguments. Changing the arguments invalidates the pending approval and creates a new request.

Denied responses

A denied tool also comes back as a content block, but there is no approval URL and no path forward. Don't retry, don't substitute another tool to reach the same outcome — the policy is intentional.

Normal failure modes

• Auth errors on OAuth integrations. If a call fails with an auth error, try once more; AgentPort attempts a token refresh automatically on the retry. If it still fails, the credentials likely need to be reconnected by an admin.
• Missing tools. If a tool you used before is no longer in the list, the integration was probably uninstalled. Don't fabricate — surface the gap to the human.
• Upstream errors. Tool results with isError: true come from the underlying vendor API. Read the text content for the real message.

What not to do

• Don't try to call the upstream service directly. You don't have credentials and AgentPort is the only path that produces an audit log entry.
• Don't rename or reformat tool names. The integration__tool form is what AgentPort routes on.
• Don't ignore approval gates by repeatedly polling or retrying. The gate will stay closed until a human acts.
• Don't omit additional_info, and don't fill it with generic filler ("calling tool"). Write a real sentence of intent.
• Don't pass opaque IDs in tool arguments without also naming or linking them in additional_info so a reviewer can verify them.