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.
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.
- Open Oversight → Cloud Agents, and select the service agent.
- Click the Activity tab. The service agent's calls appear there, attributed to it by name.
- 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 see | What it means | What to do |
|---|---|---|
| Unauthorized | The credential was missing or not recognized, or has expired | Confirm the header is sent and reaches the gateway. Then check the service agent's Credential tab for a past expiry |
Forbidden, agent_disabled | The service agent is turned off | Turn it back on from Cloud Agents |
| Forbidden | The credential is valid, but this connector is not in its scope | Add the connector under Connectors in scope, or point the caller at a connector already in scope |
| Forbidden, although the connector is in scope | The 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 so | Decide 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 list | The role on the credential may not call it | Grant the tool to that role on the Agent tools permission tab. See Controlling MCP Tool Access by Role |
| A call is blocked or held | A policy matched it | Review your policies. A held call cannot complete for a service agent, as the following caution explains |
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
hyprmcpserver 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.
Related
- Creating a Service Agent — issue the credential and set its boundary
- Managing Service Agent Credentials — rotate a credential you need to replace
- Connecting to a Gateway MCP Connector — the flow to use when a person is available to authorize