Agents Connect

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

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:

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 MCP server → Path A
• Service is a Lambda function you control → Path B
• Service has an OpenAPI spec (or you can generate one — FastAPI, ASP.NET, Spring, etc. generate OpenAPI automatically) → Path C
• Service is already fronted by API Gateway → Path C (--type api-gateway)
• None of the above and you can't add one → Path D

What Gateway is — and what it isn't

Before choosing a target type, get the mental model right. Most Gateway confusion comes from having it flipped.

Gateway hosts tools for your agent to call. The direction is:

Your agent  ───→  Gateway  ───→  Lambda function / OpenAPI API / MCP server / Smithy model
             (agent calls tool)

The agent is the client. The Gateway fronts a catalog of tools. Each tool is a Gateway target (Lambda, OpenAPI, MCP server, API Gateway, Smithy).

Gateway is not an inbound reverse proxy for your agent. If you're building an app that needs to invoke your agent, the app does not go through a Gateway. The direction is:

Your app  ───→  AgentCore Runtime  (direct invoke_agent_runtime call)

The app signs the invocation with IAM SigV4 or presents a JWT. See `agents-build/references/integrate.md` for the app-side patterns.

When you're confused about which direction you need

Ask: who is calling whom?

• "My agent needs to look up weather data" → agent is calling a tool → Gateway target (this skill, Paths A/B/C)
• "My FastAPI app needs to call my agent" → app is calling the agent → direct invocation (not Gateway; use `agents-build/references/integrate.md`)
• "My agent needs to fetch data from my FastAPI app" → agent is calling the app as a tool → Gateway target with the app exposed as an OpenAPI or REST target (Path C with your FastAPI's /openapi.json)

If you catch yourself configuring a Gateway target whose endpoint is bedrock-agentcore.<region>.amazonaws.com or pointing at your own runtime's URL, stop — you have the flow inverted.

What target type fits your tool

Your tool doesn't naturally have an OpenAPI spec and isn't an MCP server or Lambda? Either wrap it in a Lambda (simplest), generate an OpenAPI spec for it (FastAPI does this automatically), or front it with API Gateway.

Step 3: Navigate the auth matrix

This is the most common source of errors. The auth options depend on the target type, and the CLI exposes only a subset of what the API/SDK support.

| What you're connecting to | CLI --type | Outbound auth via CLI | Additional options via API/SDK |