Skip to Content
MCP GatewayConnect Agents

Connect an agent

Point an agent at SecureAuth Agent Authority so your policies decide each of its tool calls

When you finish, your agent's tool calls go through the gateway, where your policies decide each one and the audit log records it. Agents connect to the gateway over MCP (Model Context Protocol). Once connected, they can access every tool from your configured resources, governed by your policies.

The Agent Instances page with the Connect your agent dialog open on the catalog of agents
Connect on Agent Instances opens the same catalog your users get in Quickstart

Register an agent

As an admin, open Agents & NHIs and click Connect; end users self-onboard from the Quickstart page in their portal, which you hand them with Copy portal link. Both open the same catalog of agents and the same setup steps:

  1. Click your agent (Claude Code, Cursor, Copilot, Codex, and more)
  2. Follow the setup steps in the dialog. Each agent has its own configuration method
  3. Authenticate when prompted. A browser window opens for sign-in

There's nothing to copy back into the dashboard. The gateway registers the agent automatically on its first authenticated connect, and the instance appears in the list.

For agents not in the catalog, select Custom agent above the same grid, then pick how the agent authenticates:

  • Auto-register – for clients that perform their own Dynamic Client Registration. Point the agent at the gateway URL and it registers itself on first connect; there's nothing to create here.
  • API key – for clients that just need a static header token. The gateway issues a one-time opaque token that you configure in the agent.
  • OAuth – for clients that speak OAuth 2.0 but can't self-register via Dynamic Client Registration and instead ask you to hand-paste an authorization URL, token URL, client ID, and client secret into their own settings. The gateway registers an OAuth client with your organization's issuer on the agent's behalf and shows you those values.

For the latter two, copy what's shown immediately. It isn't shown again. See Custom agent for the step-by-step, and Gateway endpoints and authentication for the full detail on both credential types, including what happens when you delete the instance.

See the setup guides for each supported agent:

Scope a connection

The default URL, /gateway/mcp, gives the agent every tool from every server your organization added. Some agents cap how many tools a connection may expose, and every tool in the list costs context on each request. Connect the agent to a scoped gateway instead: one service, chosen servers of one service, or a set chosen by policy tag. See Gateway URLs for each URL and when to use it. To copy the gateway URL or build a scoped one without opening a connect dialog, use the MCP Gateway page.

Picking the scope in the connect dialog. The setup dialog (Agent Instances and Quickstart) shows a scope picker before the setup steps. Connect to defaults to All resources; pick one resource to narrow to that MCP. Upstreams appears when that resource bundles several upstreams, such as Microsoft 365 Work IQ, and narrows it to the ones you pick. Policy tags narrows further to the policy tags you pick. The dialog rewrites the URL for you.

Connect dialog for Claude with the Connect to picker open, listing resources to narrow the agent to one
The admin view of the dialog. Connect to defaults to All resources; pick one resource by name to narrow the agent to just that MCP.
Connect dialog for Claude with the Tags picker open, listing resource tags
Pick one or more tags to connect the agent to only the resources and tools carrying them.
Connect dialog for Claude with Microsoft 365 picked and the Upstreams picker open, listing Mail, Calendar, Teams, and SharePoint
Pick one or more upstreams to connect the agent to only those parts of a resource that bundles several.

Agents that need several separate scopes configure one connection each:

{
  "mcpServers": {
    "github": { "url": "https://your-gateway-url/gateway/mcp/github" },
    "dev": { "url": "https://your-gateway-url/gateway/mcp?tags=dev" },
  },
}

A scope narrows what the agent asks for. It doesn't grant or remove access. Authentication and policy enforcement are identical to the aggregate endpoint. An agent that drops the scope gets everything its policies allow. If your org has added a resource you haven't connected to yet, it behaves as on the aggregate endpoint. The gateway lists its tools, and calling one returns a link to connect your account.

Auto-registration

When an agent connects for the first time, the gateway automatically detects its type and records metadata like client name, version, and protocol version. The type comes from the client name. When the client name matches no known agent, as SDK defaults such as mcp don't, the gateway uses the user agent instead. An agent that neither identifies is listed as Unknown. The agent appears in the dashboard immediately.

Registry vs. Instances

Once connected, the agent appears in two views: the Agent registry, one card per agent product, and Agents, each person's agents and their connected instances, with each instance's identity, activity and effective access.

Connect accounts to services

The first time your agent tries to use a tool that requires authentication (for example, Slack), the gateway will prompt you with a link to connect your account. No upfront setup needed. See Connections for details.

Next steps

Continue to Monitor activity to watch these tool calls appear in the dashboard and audit log. For client-specific setup, see the Claude Code guide or the other supported agents listed above.

On this page