---
title: "Resolve a free-form query to an MCP server"
method: POST
path: "/v1/mcp-connections/resolve"
tags: ["Authentication"]
---

# Resolve a free-form query to an MCP server

`POST /v1/mcp-connections/resolve`

Admin-only, side-effect-free smart resolution for the add-connection flow. Accepts a URL, a bare host, or a product name ("vercel"), matches curated presets, probes bounded well-known endpoint candidates through the SSRF-guarded discovery fetch, and returns the winning URL with its requirements discovery. It performs no client registration, credential write, or connection creation.

## Request body

- ExternalMcpResolveInput
  - `query` string, required

## Response `200`

Resolution result (not_found is a successful outcome).

- ExternalMcpResolveResult
  - `resolution` 'preset' | 'discovered' | 'not_found', required
  - `attempted` string[], required
  - `reason` string
  - `preset` ExternalMcpPresetResponse
    - `presetId` string, required
    - `displayName` string, required
    - `description` string, required
    - `url` string, required
    - `authType` 'oauth' | 'apikey' | 'none', required
    - `requiresOAuthClient` boolean
    - `authorizationServerIssuer` string, uri
    - `defaultOAuthScopes` string[]
  - `match` object
    - `url` string, required
    - `suggestedName` string, required
    - `discovery` ExternalMcpRequirementsDiscovery, required
      - `status` 'ready' | 'manual_action_required' | 'unsupported' | 'unreachable', required
      - `server` object, required
        - `url` string, required
        - `protocolVersion` string
        - `initialize` 'succeeded' | 'authentication_required' | 'failed', required
      - `authentication` object, required
        - `kind` 'none' | 'oauth' | 'manual_bearer' | 'unknown', required
        - `resource` string
        - `protectedResourceMetadataUrl` string
        - `authorizationServers` object[], required
          - `issuer` string, required
          - `authorizationEndpoint` string
          - `tokenEndpoint` string
          - `registrationEndpoint` string
          - `clientIdMetadataDocumentSupported` boolean, required
          - `scopesSupported` string[]
          - `grantTypesSupported` string[]
          - `codeChallengeMethodsSupported` string[]
          - `tokenEndpointAuthMethodsSupported` string[]
        - `requiredScopes` string[], required
        - `recommendedScopes` string[], required
        - `refreshSupport` 'supported' | 'not_advertised' | 'unknown', required
        - `availableRegistrationMethods` string[], required
        - `recommendedRegistrationMethod` 'client_metadata' | 'dynamic' | 'pre_registered', required
      - `tools` object, required
        - `visibility` 'available_without_auth' | 'requires_auth' | 'unavailable', required
        - `count` integer
        - `items` object[]
          - `name` string, required
          - `readOnlyHint` boolean
          - `destructiveHint` boolean
          - `openWorldHint` boolean
      - `manualRequirements` object[], required
        - `code` string, required
        - `label` string, required
        - `reason` string, required
        - `required` boolean, required
      - `warnings` object[], required
        - `code` string, required
        - `message` string, required

## Other responses

- `400` — Invalid request.
- `401` — The caller must be signed in.
- `403` — Only workspace owners and admins can resolve MCP servers.

---

[API](https://skmtc.net/openworklabs/apis/den-api.md) · [All operations](https://skmtc.net/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openworklabs/den-api/revisions/805150503452/schema)