/agents-connect

name: agents-connect
description: >
  Use when connecting your agent to external APIs, tools, or services via
  Gateway, or restricting tool access with Cedar policies. Handles gateway
  setup, target types, outbound auth (OAuth, API key, IAM), credentials,
  and Cedar policy authoring. Triggers on: "connect to API", "add gateway",
  "connect to MCP server", "Lambda tools", "OpenAPI", "gateway target",
  "Cedar policy", "restrict tools", "policy engine", "gateway auth error",
  "store API key", "outbound credential", "env var API key", "API key None
  after deploy", "credential not available after deploy",
  "should this be a gateway target", "give my agent tools",
  "add tools to agent".
  Not for inbound auth (who can call your agent) — use agents-harden.
  Not for debugging agent behavior — use agents-debug.
  Not for VPC networking errors (agent can't reach APIs due to VPC) — use
  agents-build. Not for creating or hosting a new MCP server project — use
  agents-get-started.
allowed-tools: Read Grep Glob Bash
metadata:
  type: skill
  version: "1.0.0"
  author: aws-agentcore
  requires-cli: ">=0.9.0"

connect

Give your AgentCore agent access to external APIs, tools, and services via the AgentCore Gateway — and control what it can access with Cedar policies.

When to use

• You want your agent to call an external API or MCP server
• You want to expose Lambda functions as agent tools
• You have an OpenAPI spec you want to turn into agent tools
• Your agent needs credentials to call an external service
• You want to restrict which tools your agent can call (Cedar policies)
• You want role-based or amount-based access control on tool calls
• A gateway connection, tool call, or policy authorization is failing

For adding Cedar policies to control tool access, load [`references/policy.md`](references/policy.md).

Input

`$ARGUMENTS` is optional:

/connect                    # interactive — asks what you're connecting to
/connect mcp                # MCP server setup
/connect lambda             # Lambda function as tools
/connect openapi            # OpenAPI schema as tools
/connect credential         # Add a credential for outbound auth

Process

Step 0: Verify CLI version

Run `agentcore --version`. This skill requires v0.9.0 or later. If the version is older, tell the developer to run `agentcore update` before proceeding.

Step 1: Read the project

Read `agentcore/agentcore.json` to understand:

• What framework the project uses
• What gateways and targets are already configured (in the `agentCoreGateways` array)

**If no project context:** Ask what they're trying to connect to and proceed with the appropriate pattern.

Step 2: Identify what they're connecting to

Ask (or infer from `$ARGUMENTS`):

> "What are you connecting your agent to? > > 1. An external MCP server (e.g., a third-party tool provider) > 2. A Lambda function you've written > 3. An API with an OpenAPI spec > 4. An AWS API Gateway REST API > 5. An external service with no OpenAPI spec, MCP server, or Lambda in front of it — and you can't add one"

**Options 1–4 front the service as a Gateway target.** This is the default path: the gateway handles outbound auth via its credential providers (so the agent code never sees the secret), the tool becomes discoverable over MCP, and policy engines can authorize or deny calls at the edge. Pick the target type that matches the service.

**Option 5 is Path D** — register a credential and call the API directly from agent code. This is the fallback when fronting isn't practical; the skill walks through when it's appropriate and when it isn't.

---

Default: prefer a Gateway target over direct API calls in code

Before jumping into paths, set expectations. Most "my agent needs to call X" requests land on a Gateway target — not on `httpx` inside the entrypoint.

**Why Gateway is the default:**

• **Credential injection at the edge.** Gateway's credential providers (OAuth, API key, IAM) attach auth to the outbound request. The agent code calls `session.call_tool(...)` — it never touches the secret. Agent code that does `client = openai.OpenAI(api_key=...)` is one leaked prompt / log line / traceback away from exfiltrating the key.
• **Discoverable tool catalog.** Tools are listed by the MCP server; the framework (Strands, LangGraph, etc.) binds them automatically. Adding a tool is an `agentcore add gateway-target` + redeploy, not a code change.
• **Policy enforcement.** Cedar policies can authorize or deny tool calls per principal, per tool, per argument value. This is impossible when tool calls are buried in `httpx.post(...)` inside agent code.
• **Semantic search.** Once the catalog has 20+ tools, `x_amz_bedrock_agentcore_search` selects the relevant ones per turn.

**When a direct API call in agent code is the right answer:**

| Situation | Why Gateway isn't right | What to do | |---|---|---| | Streaming/bidirectional protocol (SSE with live output, WebSockets, WebRTC, long-polling) | Gateway's MCP transport doesn't front those yet | Direct call, Path D | | Latency hot path where the MCP hop is measurable and the trade-off is accepted | Extra network hop | Direct call, Path D, with measurement to back the decision | | Vendor proprietary protocol / binary SDK | No HTTP surface for Gateway to front | Use the vendor SDK directly, Path D for any secrets | | Calling another agent via A2A | A2A is HTTP-by-design and has its own auth model | [`agents-build/references/multi-agent.md`](../agents-build/references/multi-agent.md), not a Gateway target | | AWS service SDK (S3, DynamoDB, SQS, etc.) the runtime already has IAM for | No auth value in fronting — adds hops | Direct boto3 call with the runtime's execution role |

For **every other case**, recommend a Gateway target. If the developer insists on a direct call, ask which of the five situations above applies. If none, steer them back to a Gateway target.

**Triage heuristic:**

• Service has an MC