List an upstream's tools again

Answers 404 where the mcp-upstreams feature is off. Lists the server’s tools again. Adopted tools are never changed here: one whose definition changed shows state: changed and is refused at dispatch until it is re-adopted. A listing that fails keeps the last good one and sets lastError.

POST/api/v2/mcp-upstreams/{id}/refresh

Authorization

AuthorizationBearer token (Anlyon API key) · headerrequired

Workspace API key sent as Authorization: Bearer <key>.

better-auth.session_tokenAPI key · cookierequired

Browser session used by dashboard-only operations.

Path parameters

idstringrequired

The upstream's id (mcpu_...).

matches ^mcpu_[A-Za-z0-9_-]+$

Header parameters

X-Request-Idstring

Optional caller correlation ID. Unsafe or oversized values are replaced.

max length 128

Responses

200

The upstream, with its new listing.

successbooleanrequired

dataMcpUpstreamrequired

Show properties

idstringrequired

namestringrequired

urlstring<uri>required

headersobjectrequired

Sent on every request. Credentials appear only as secret references.

registryNamestring | nullrequired

protocolVersionstring | nullrequired

transportstring | nullrequired

How the server is reached, as the last listing found: Streamable HTTP, or the older HTTP+SSE transport (MCP 2024-11-05) Anlyon falls back to when the server answers 400, 404 or 405. Null until a listing has worked.

Allowed:streamable-httpssenull

serverInfoobject | nullrequired

toolsMcpToolSnapshot[]required

Show properties

Array of McpToolSnapshot

namestringrequired

hashstringrequired

sha256 of the tool's normalised definition

definitionobjectrequired

suggestedClassstringrequired

Allowed:readwriteirreversibledestructive

reasonsstring[]required

schemaCheckMcpSchemaCheckrequired

How a tool's arguments are checked. full: against its whole input schema (JSON Schema drafts 2020-12, 2019-09, 07 and 04). loose: the schema uses something Anlyon does not check, so only that the arguments are a JSON object of at most 256 KiB. A loose tool is still pinned by hash, and approval is always suggested for it.

Allowed:fullloose

schemaCheckReasonMcpSchemaCheckReason | nullrequired

Why a tool is loosely checked; null when it is checked in full. remote_ref: a $ref points outside the schema, and nothing is fetched. too_large: the schema is past a size, depth or reference limit. unsafe_pattern: a pattern could backtrack catastrophically or is too long. invalid_schema: the schema is not valid JSON Schema. unsupported_keyword: $dynamicRef or $recursiveRef. unknown_dialect: $schema names a dialect Anlyon does not know. ref_cycle: a $ref leads back to itself without moving into the value.

Allowed:remote_reftoo_largeunsafe_patterninvalid_schemaunsupported_keywordunknown_dialectref_cyclenull

toolsHashstring | nullrequired

The hash of the whole listing

listedAtstring<date-time> | nullrequired

lastErrorobject | nullrequired

listedWithstring | nullrequired

How the last listing was made: without a credential, with the headers, or with the operator's own OAuth grant.

Allowed:anonymousheadersoperatornull

checkobjectrequired

Whether Anlyon can re-list the server by itself, and when it last tried.

Show properties

statusstringrequired

failed: nothing is known since listedAt. needs_sign_in: it cannot be checked until someone connects their own account. An end user's sign-in is never used for it.

Allowed:okfailedneeds_sign_inpending

checkedAtstring<date-time> | nullrequired

nextCheckAtstring<date-time> | nullrequired

failuresintegerrequired

Failed checks in a row.

changesobject[]required

How the last listing differs from what was adopted. Finding a change adopts nothing and enables nothing. tool and before are the server's text, untrusted.

Show properties

Array of object

toolstringrequired

kindstringrequired

changed and removed are adopted tools, refused at dispatch until re-adopted. added is shown and never adopted.

Allowed:changedremovedadded

actionstring | nullrequired

actionIdstring | nullrequired

pinnedHashstring | nullrequired

currentHashstring | nullrequired

suggestedClassstring | nullrequired

Allowed:readwriteirreversibledestructivenull

beforeobject | nullrequired

The definition at the pin

detectedAtstring<date-time>required

oauthobject | nullrequired

Set for an upstream that signs people in with OAuth (ADR 0026). Never a token or a secret.

Show properties

resourcestring<uri>required

issuerstring<uri>required

authorizationServersstring[]required

Every authorization server the resource named; issuer is the one in use.

authorizationEndpointstring<uri>required

tokenEndpointstring<uri>required

scopesSupportedstring[]required

scopesstring[]required

clientIdstringrequired

The operator's client id

clientRegistrationstringrequired

Allowed:pre_registeredclient_metadata_documentdynamic

advertisedobjectrequired

Show properties

dynamicRegistrationbooleanrequired

clientIdMetadataDocumentsbooleanrequired

pkceS256booleanrequired

publicClientbooleanrequired

redirectUristring<uri>required

operatorConnectedbooleanrequired

adoptedobject[]required

Show properties

Array of object

toolstringrequired

actionstringrequired

actionIdstringrequired

enabledbooleanrequired

statestringrequired

Allowed:currentchangedmissing

toolHashstringrequired

The definition this action is pinned to.

requiresApprovalbooleanrequired

schemaCheckMcpSchemaCheckrequired

Allowed:fullloose

schemaCheckReasonMcpSchemaCheckReason | nullrequired

Allowed:remote_reftoo_largeunsafe_patterninvalid_schemaunsupported_keywordunknown_dialectref_cyclenull

archivedAtstring<date-time> | nullrequired

createdAtstring<date-time>required

updatedAtstring<date-time>required

401

Unauthorized - Invalid or missing API key

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

How to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

403

Authenticated credential lacks the required scope or workspace access.

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

404

Not Found - Resource does not exist

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

429

Too Many Requests - Rate limit exceeded. A workspace's API requests are limited per minute and per UTC clock hour by plan; Retry-After says when to try again, and an hourly refusal names the limit and when the count resets. Successful responses carry the same limits in X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (the minute) and X-RateLimit-Limit-Hour, X-RateLimit-Remaining-Hour, X-RateLimit-Reset-Hour (the hour).

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (Anlyon API key)Remember on this deviceInclude my values in samples

Parameters

X-Request-IdheaderOptional caller correlation ID. Unsafe or oversized values are replaced.idpath*The upstream's id (mcpu_...).

Request

curl -X POST 'https://api.anlyon.com/api/v2/mcp-upstreams/string/refresh' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("https://api.anlyon.com/api/v2/mcp-upstreams/string/refresh", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.post(
    "https://api.anlyon.com/api/v2/mcp-upstreams/string/refresh",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "success": true,
  "data": {
    "id": "mcpu_01JABCDEF",
    "name": "mailer",
    "url": "http://example.com",
    "headers": {
      "property1": "string",
      "property2": "string"
    },
    "registryName": "string",
    "protocolVersion": "string",
    "transport": "streamable-http",
    "serverInfo": {},
    "tools": [
      {
        "name": "string",
        "hash": "string",
        "definition": {},
        "suggestedClass": "read",
        "reasons": [
          "string"
        ],
        "schemaCheck": "full",
        "schemaCheckReason": "remote_ref"
      }
    ],
    "toolsHash": "string",
    "listedAt": "2019-08-24T14:15:22Z",
    "lastError": {},
    "listedWith": "anonymous",
    "check": {
      "status": "ok",
      "checkedAt": "2019-08-24T14:15:22Z",
      "nextCheckAt": "2019-08-24T14:15:22Z",
      "failures": 0
    },
    "changes": [
      {
        "tool": "string",
        "kind": "changed",
        "action": "string",
        "actionId": "string",
        "pinnedHash": "string",
        "currentHash": "string",
        "suggestedClass": "read",
        "before": {},
        "detectedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "oauth": {
      "resource": "http://example.com",
      "issuer": "http://example.com",
      "authorizationServers": [
        "string"
      ],
      "authorizationEndpoint": "http://example.com",
      "tokenEndpoint": "http://example.com",
      "scopesSupported": [
        "string"
      ],
      "scopes": [
        "string"
      ],
      "clientId": "string",
      "clientRegistration": "pre_registered",
      "advertised": {
        "dynamicRegistration": true,
        "clientIdMetadataDocuments": true,
        "pkceS256": true
      },
      "publicClient": true,
      "redirectUri": "http://example.com",
      "operatorConnected": true
    },
    "adopted": [
      {
        "tool": "string",
        "action": "string",
        "actionId": "string",
        "enabled": true,
        "state": "current",
        "toolHash": "string",
        "requiresApproval": true,
        "schemaCheck": "full",
        "schemaCheckReason": "remote_ref"
      }
    ],
    "archivedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "requestId": "req_0123456789abcdef0123456789abcdef",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {},
    "fix": {
      "summary": "Log in again and approve the anlyon:secrets consent group, which grants secrets:write.",
      "command": "anlyon auth login --scope anlyon:secrets",
      "url": "https://console.anlyon.com/settings/api-keys",
      "docs": "https://docs.anlyon.com/cli/authentication"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}