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

REST APIs

A REST API connector turns API operations into Model Context Protocol (MCP) tools. Agents call the connector through HYPR AgentPass™. The gateway authenticates the caller, evaluates policy and records the request. It then sends the corresponding REST request, with the credentials you configure.

Before You Begin​

Prepare one of these API descriptions:

  • OpenAPI 3.x document
  • Swagger 2.0 document
  • Postman collection

You can paste the description, or provide a URL that AgentPass can refresh. Check that each operation has a clear summary and stable parameter names. They become the tool description and input schema an agent sees.

The description must be self-contained. AgentPass refuses an OpenAPI or Swagger description with a $ref that points outside the document, such as to another file or a URL. Bundle referenced files into one document first.

Create the Connector​

  1. Open All Connectors → Add Connector → REST APIs → REST API (MCP). The Add API connector page opens.
  2. Enter a Connector name and, optionally, a Display name.
  3. Under Spec source, choose Paste or URL.
  4. Paste the API description, or enter its URL.
  5. Enter a Base URL override if the description does not contain an absolute server URL. When it is blank, the gateway uses the description's first server.
  6. Optional: Turn on Allow private network addresses, only for a trusted internal API you control. It is off by default. See Allow a Private Network Address.
  7. Choose the Downstream authentication, described in the following section.
  8. Complete the method's fields.
  9. Click Register. The result lists the generated tools.
  10. Click Open connector.
  11. On the Tools tab, review the generated tools.
  12. Before you assign the connector to agents, test representative read and write operations on its Test tab.

Each API operation becomes one MCP tool. AgentPass uses the operation ID as the tool name when one is available. Otherwise, it generates a stable name from the method and path.

When the API has more than 50 operations, the result warns that many MCP clients cap the tool list. For such an API, use a smaller, curated description.

To register another API, click Add another on the result.

Choose Downstream Authentication​

Downstream authentication is how the gateway authenticates to the API.

MethodUse it when
NoneThe API does not require credentials
Bearer tokenEvery approved caller uses one token stored by the gateway
API key (custom header)The API expects one stored key in a header you name
OAuth — service (client credentials)The gateway obtains one client-credentials token for the connector
OAuth — per-user (3-legged)Each person authorizes their own account through an OAuth consent flow

Secrets are write-only after saving. For OAuth — per-user (3-legged), register the redirect URI the form shows with your OAuth provider.

To connect a person's account from the console, click Connect… on the registration result, or Connect a user… on the connector's Connection tab. Enter the person's email, and complete the authorization in the window that opens. AgentPass refreshes the person's token when the provider supports refresh tokens.

Scope API credentials narrowly

The gateway can perform every operation the configured credential permits. Limit the credential to the operations agents need. Use AgentPass policies to require approval for consequential tools.

Connect an Agent​

The connector is available at:

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

Add that gateway URL to the agent, not the REST API's own URL. See Connecting to a Gateway MCP Connector for a manual Jira example. Managed cloud agents and Managed Desktop Tools can receive the connector directly from the AgentPass console.

Example​

Suppose an issue-tracking API defines GET /issues/{key} and POST /issues. AgentPass exposes them as tools such as getIssue and createIssue. When an agent calls one:

  • The agent supplies the path, query and body fields defined by the API description.
  • AgentPass adds the configured API credential.
  • A policy can allow reads, and require approval for createIssue.
  • The Request Log records the agent, person, tool and outcome.

The agent works with MCP tools. It never constructs HTTP requests or holds the API credential.

The Connection and Test Tabs​

A REST API connector has two tabs of its own, besides Tool calls and Tools.

TabWhat you do there
ConnectionChange the Base URL, Allow private network addresses and the Authentication mode with its credentials. Leave a secret blank to keep it. Click Save credentials to save, Validate connection to check the connection, or Connect a user… to connect a person's account
TestPick a tool, enter its Arguments (JSON) and click Invoke to see the response, its status and latency. For per-user OAuth, enter the person whose token to use under Run as supervisor (USER_OAUTH)
The Test tab bypasses policy

A call from the Test tab goes straight to the API. Policy and approval rules do not apply to it. Real agent traffic still goes through them.

Changing the client ID or secret of a per-user OAuth connection invalidates the connected accounts. Each person then connects their account again.

Maintain the Connector​

For a URL-based description, AgentPass refreshes the tool catalog, and keeps the last valid version if a refresh fails, including when the new version references something outside the document. Review the Tools tab after the API description changes, especially when operation IDs, required parameters or response shapes change.