Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.0

Connecting a Service Agent

Overview​

A service agent authenticates to HYPR AgentPass™ by sending its credential on every request. There is no sign-in step, no browser handshake and no first-connection approval. You configure the credential once in the calling system, and it works from the next request.

This page covers what the calling system sends, how to confirm it works, and what the gateway's answer means when it refuses a call.

Present the Credential​

The calling system sends the credential in the standard HTTP Authorization header, with the Bearer scheme:

Authorization: Bearer hypr_sa_your-credential-here

MCP clients and agent frameworks generally have a setting for a static header or a bearer token. Set it there, alongside the server URL. Read the value from your secrets manager instead of writing it into a configuration file.

Point It at a Connector​

A service agent reaches a connector at your gateway URL, followed by the connector's path:

https://<your-gateway-url>/<connector-name>/mcp

Use the name of a connector in the credential's scope. Your HYPR representative or administrator provides the gateway URL.

Where service agents fit

A service agent is built for connectors where the gateway holds the credential to the target:

  • An MCP server the gateway authenticates to on your behalf
  • A server whose OAuth tokens the gateway manages
  • A REST API connector exposed to agents as MCP tools

On those connectors, the service agent's credential identifies the caller, and the gateway supplies the credential to the target.

Verify the First Call​

Confirm the connection in the console, not in the calling system's own logs.

  1. Open Oversight → Cloud Agents, and select the service agent.
  2. Click the Activity tab. The service agent's calls appear there, attributed to it by name.
  3. Optional: Open the Request Log to see the same traffic alongside the rest of your agent activity.

A service agent that has made no calls yet has an empty Activity tab. If the calling system reports an error and nothing appears there, the credential is not reaching the gateway. Check that the header is sent, and that the URL names a connector, not the gateway root.

When the Gateway Refuses a Call​

The gateway separates two kinds of refusal: it does not know who is calling, or it knows and the caller may not do that. The response you get points to the cause.

What you seeWhat it meansWhat to do
UnauthorizedThe credential was missing or not recognized, or has expiredConfirm the header is sent and reaches the gateway. Then check the service agent's Credential tab for a past expiry
Forbidden, agent_disabledThe service agent is turned offTurn it back on from Cloud Agents
ForbiddenThe credential is valid, but this connector is not in its scopeAdd the connector under Connectors in scope, or point the caller at a connector already in scope
Forbidden, although the connector is in scopeThe call would have used the owner's connected account, and the connector is not on the credential's act-as-owner list. The message says soDecide whether this service agent should act as its owner there. If so, add the connector under May act as the owner on. See Acting as the owner
A tool is missing from the listThe role on the credential may not call itGrant the tool to that role on the Agent tools permission tab. See Controlling MCP Tool Access by Role
A call is blocked or heldA policy matched itReview your policies. A held call cannot complete for a service agent, as the following caution explains
Approval policies and service agents

A policy that requires supervisor approval cannot complete for a service agent, because nobody is there to approve it. When a service agent's traffic can match a policy, choose allow or block instead of require approval. Alternatively, scope the policy so it applies only to supervised agents.

What a Service Agent Cannot Do​

Some capabilities need a person, so a service agent does not have them:

  • The gateway's own tools. Onboarding, approvals and supervisor messaging come from the hyprmcp server described in Connecting to a Gateway MCP Connector. A service agent cannot use them.
  • Conversations. There is no supervisor to message, so the chat surface does not apply.
  • Automations and assignments. No person drives a service agent, so it is not assigned to one.

The console does not offer these for a service agent, and the gateway refuses them if a caller requests them directly.