Skip to main content
Glama

Configure an MCP server for Clerk OAuth

configure_mcp_server
DestructiveIdempotent

Register an MCP server URL as an OAuth resource on an instance so Clerk issues access tokens with that URL as the audience. The first MCP server on an instance also turns on the audience claim and CIMD client registration; later servers leave OAuth settings as they are and report settings that still block MCP clients. Registering a marked URL changes nothing; an eligible legacy Dashboard registration with the same URL is marked as an MCP server. Pass replace_resource_url to replace a registered URL (the URI of a resource cannot be edited). Pass dry_run: true to see what would change without saving. After a save the tool requests a public discovery check when a checker is available.

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": {
      "application_id": "<application_id>",
      "instance": "<instance>",
      "resource_url": "<resource_url>"
    },
    "name": "configure_mcp_server"
  }
}

Input Schema

NameRequiredDescriptionDefault
dry_runNoPreview the change without saving it.
instanceYesInstance to target: "development", "production", or a full instance ID (ins_…).
resource_urlYesPublic https URL of the MCP server, e.g. https://mcp.example.com/mcp.
application_idYesClerk application ID (app_…).
replace_resource_urlNoA registered MCP server URL to replace with resource_url. Omit to add resource_url.

Output Schema

NameRequiredDescriptionDefault
noteYes
checkYes
mcp_serverYes
next_stepsYes
instance_idYes
resource_urlYes
setup_promptYes
configurationYes
application_idYes
end_to_end_verifiedYes
authorization_serverYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • removedOutput schema / properties / authorization_server / properties / issuer / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / authorization_server / properties / issuer / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / check / properties / freshness / properties / age_seconds / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / check / properties / freshness / properties / age_seconds / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / check / properties / freshness / properties / checked_at / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / check / properties / freshness / properties / checked_at / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  2. Added

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing side effects the agent could not infer: the first server flips on the audience claim and CIMD client registration, later servers leave OAuth settings untouched, a marked URL is a no-op, and an eligible legacy Dashboard registration gets converted. It also explains the post-save discovery check and the immutability of a resource URI, consistent with destructiveHint=true rather than contradicting it.

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-loaded with purpose, then behavior, with zero filler sentences. It is dense and a few clauses ('Registering a marked URL changes nothing') are terse enough to require a second read, but nothing is redundant.

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 destructive, open-world mutation with an output schema, the description covers side effects, no-op cases, and preview mode thoroughly. It omits prerequisite permissions/authentication requirements and failure modes, which is the main remaining gap.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all five parameters including dry_run and instance formats. The description adds only the rationale that a resource URI cannot be edited (explaining replace_resource_url); otherwise it restates schema semantics, so baseline 3 applies.

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

Purpose5/5

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

States a precise verb and resource — register an MCP server URL as an OAuth resource on an instance — plus the downstream effect (Clerk issues tokens with that URL as audience). That specificity is unique among the siblings (e.g. check_mcp_server only verifies), so an agent can identify the tool without opening the schema.

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 conditional usage context: first server on an instance vs later servers, when to pass replace_resource_url, and when to use dry_run: true. It never names an alternative tool or an explicit 'do not use this for X' exclusion, so it falls short of a 5.

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