Skip to main content
Glama

Authorize Mcp OAuth

authorizeMcpOAuth

Start an OAuth-based connection with a remote MCP server. Returns an authorization URL the user must open in a browser; once they grant consent, Duvo creates the matching connection and redirects the browser to the optional return_url. A new connection to a custom MCP server needs custom_integration_id (register the server first with POST /v2/teams/:team_id/integrations/custom) and is refused with 400 without it; a catalog integration such as NetSuite or Asana takes integration_type instead.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "mcp_server_url": "<mcp_server_url>",
      "name": "<name>"
    },
    "name": "authorizeMcpOAuth"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesHuman-readable name to display for the connection.
team_idNoDuvo team UUID to operate on. API keys are pinned to a single team — omit this (it falls back to the key's team) or pass that same team; a different team is rejected. OAuth callers, who can span multiple teams, should pass the target team here.
return_urlNoWhere to send the user's browser after consent completes. Accepts an absolute URL on a domain Duvo allows, or a path relative to the Duvo frontend (e.g. `/integrations/slack`).
mcp_server_urlYesURL of the MCP server requiring OAuth.
oauth_client_idNoOAuth client ID of a client the user registered on the authorization server themselves (e.g. a NetSuite Integration record). Takes precedence over preregistered credentials and Dynamic Client Registration. Cannot be combined with custom_integration_id: for a custom MCP server, put the client credentials on the custom integration instead (oauth_client_id and oauth_client_secret on POST /teams/{teamId}/integrations/custom). For a new connection this applies to catalog integrations such as NetSuite. On reconnect, omit to reuse the connection's stored credentials, or provide to replace (rotate) them.
integration_typeNoOptional catalog integration type (e.g. `netsuite`, `asana`). When it names a known MCP OAuth catalog integration and `mcp_server_url` matches that integration's registered server, the connection is treated as a catalog connection; otherwise it requires the custom MCP servers capability.
oauth_client_secretNoClient secret for `oauth_client_id`. Omit for public clients (PKCE-only).
custom_integration_idNoID of the custom integration this connection is for. Required for a new connection to a custom MCP server; omit it for a catalog integration such as NetSuite. On reconnect, pass the connection's own custom integration ID, or omit it only for a connection that has none.
reconnect_instance_idNoWhen set, the OAuth flow will update the existing connection in place rather than creating a new one.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / custom_integration_id / description
      Previous value: -"Optional ID of a custom integration this connection should be associated with."New value: +"ID of the custom integration this connection is for. Required for a new connection to a custom MCP server; omit it for a catalog integration such as NetSuite. On reconnect, pass the connection's own custom integration ID, or omit it only for a connection that has none."
    • changedInput schema / properties / oauth_client_id / description
      Previous value: -"OAuth client ID of a client the user registered on the authorization server themselves (e.g. a NetSuite Integration record). Takes precedence over preregistered credentials and Dynamic Client Registration. Cannot be combined with custom_integration_id. On reconnect, omit to reuse the connection's stored credentials, or provide to replace (rotate) them."New value: +"OAuth client ID of a client the user registered on the authorization server themselves (e.g. a NetSuite Integration record). Takes precedence over preregistered credentials and Dynamic Client Registration. Cannot be combined with custom_integration_id: for a custom MCP server, put the client credentials on the custom integration instead (oauth_client_id and oauth_client_secret on POST /teams/{teamId}/integrations/custom). For a new connection this applies to catalog integrations such as NetSuite. On reconnect, omit to reuse the connection's stored credentials, or provide to replace (rotate) them."
  2. First observed

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly=false, openWorld=true, non-idempotent and non-destructive. The description goes well beyond them: it explains the human-in-the-loop flow (user opens the URL and grants consent), that Duvo then creates the connection, the redirect to the optional return_url, and a specific failure mode (400 without custom_integration_id). It also discloses credential precedence and the in-place reconnect behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and return value in the first sentence, then moves to prerequisites. The third sentence is long and packs several conditional rules together, but every clause carries decision-relevant information, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, non-idempotent, open-world mutation with no output schema, the description covers the flow, the returned artifact, the redirect, and the main validation failure. It omits permission/auth scope requirements and what the connection object looks like, but those are secondary for an agent deciding whether to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the schema carries the per-parameter detail; the description's added value is the cross-parameter decision rule (custom_integration_id vs integration_type) and the note that return_url is optional, which helps an agent assemble a valid call. It does not add format or syntax detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Start an OAuth-based connection with a remote MCP server,' and immediately clarifies the return value is an authorization URL the user must open. This is clearly distinguishable from a status-check sibling like checkMcpOAuth, though the description never names an alternative tool explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete conditional guidance: a new custom MCP server needs custom_integration_id and is refused with 400 without it, while a catalog integration such as NetSuite or Asana takes integration_type instead. It does not say when to use this versus checkMcpOAuth or startNativeOAuth, so the guidance is scenario-based rather than alternative-based.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources