Skip to main content
Glama

Update a service datasource

update_service_datasource
Destructive

Replace a Custom or MCP service datasource's declaration while its status is configuring, failed or selected, and mint a fresh credential page. Send the complete credentials declaration (name, label, help, required, secret), auth for OAuth sign-in, or no_credentials: true for a public service. Custom OAuth auth is {type: "oauth2", resource: "", scopes: ["platform:read"]}. Omitted scopes — and an empty array, which Admin omits the same way — take the scopes of the operator's allowlist entry for the discovered authorization server: the scopes actually requested are that entry's, never this call's. Omitted auth preserves the stored declaration, and an OAuth declaration is never removed from a datasource: auth is replaced whole, there is no clear, and no_credentials or credentials cannot be combined with auth — a datasource that has signed in once keeps signing in. An auth re-sent with scopes that differ from the stored ones, including an auth that omits scopes the datasource has stored, is a changed declaration: it creates a new connection instead of re-linking. A failed OAuth connection with an unchanged declaration re-links in place; changing auth, label or credentials creates a new connection. The Administrator must sign in on the hosted credential page, with no pasted token; OAuth becomes ready only after sign-in completes. Preserves the datasource and Setup steps. For an MCP datasource send the complete mcp declaration instead, including the unchanged mcp.oauth object if used; directory URLs default from the card. Never mix it with credentials, no_credentials or top-level auth. MCP detection and Test and finish govern readiness. Refuses other catalogue cards and databases. An omitted label keeps the title the datasource already carries; send label to change it. Refuses with connector_republish_required once a connector is bound to the datasource - even while it is settling failed - because that connector's manifest reads the credential names it was published with, and publish_module_version is what moves both; a connected datasource is refused with already_connected. The answer carries human_link; the credential never passes through this conversation. Requires the project's datasource-management grant and an Administrator caller.

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": {
      "datasource_id": "<datasource_id>"
    },
    "name": "update_service_datasource"
  }
}

Input Schema

NameRequiredDescriptionDefault
mcpNoNative MCP server or directory card only. Declare the HTTPS server URL (directory cards default to their endpoint), optional auth mode, header names and OAuth client metadata. Never include header values or secrets. Refused with credentials, no_credentials or top-level auth. OAuth availability and detection are decided by Request Service.
authNoCustom only: OAuth sign-in on the hosted credential page, with no pasted token. Declare the protected HTTPS resource; scopes are optional, and omitted or empty scopes take the scopes of the operator's allowlist entry for the discovered authorization server, never this call's. Omit auth on update to preserve the stored declaration: an OAuth declaration is replaced whole and never removed.
labelNoCustom only: what the credential page calls the service, e.g. "ISS tracker" or "Stripe (test mode)". update_service_datasource keeps the title the datasource already carries when this is omitted; send it to change the title, blank included to clear it
credentialsNoCustom only: what the page asks for, one object per credential — name (the environment variable the connector reads, e.g. STRIPE_API_KEY), label (what the page calls it), secret (stored write-only; true for keys and tokens), required (the page cannot be marked ready without it), help (where the person finds it). Names only, never a value.
datasource_idYesThe Custom or MCP service datasource UUID
application_idNoOptional Application UUID whose build this call serves (Administrator only). Setup steps this call opens record it, so they show on that Application's build screen; the resources themselves stay shared by the Project. A shared step it reuses keeps the Application it was opened for, so a step it returns may be watchable with get_setup_journal only without application_id. Use the build's application_id, the one you call describe_application with.
no_credentialsNoCustom only: the service needs no credential at all (a public feed); the page then asks for nothing

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior3/5

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

Annotations already declare destructive=true, readOnly=false, idempotent=false and openWorld=true, so the mutation/reversibility profile is covered structurally. On top of that the description adds genuinely non-obvious behavior: re-link vs new connection semantics, that an OAuth declaration is never removed, that a changed scope set creates a new connection, and that connector_republish_required fires even while the datasource is settling failed. It still does not state whether delivered credentials are atomic across upstream use, though it does say the answer carries human_link.

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

Conciseness3/5

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

Purpose and preconditions are front-loaded in sentence one, but the body is a dense run-on block that restates much of the input-schema prose (scopes/allowlist, auth replacement, mcp.exclusion rules) and repeats the no_credentials/auth combination rule twice. It is information-rich but demands re-reading, which costs an agent scanning for call-time facts.

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

Completeness5/5

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

For a 7-parameter destructive tool with nested objects and no output schema, the definition covers preconditions, payload variants, refusal cases, permission requirements (datasource-management grant plus Administrator caller), the Administrator sign-in flow, and the return shape (human_link, credential never in the conversation). Nothing an agent needs before calling it is missing.

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 100%, so the baseline is 3, but the description adds consequences the schema cannot express: omitted scopes falling back to the operator's allowlist entry (never this call's scopes), an empty array being treated as omitted, omitted auth preserving the stored declaration, omitted label preserving the existing title, and directory URLs defaulting from the card.

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?

Opens with a specific verb and resource ('Replace a Custom or MCP service datasource's declaration') plus the exact statuses it is valid in ('configuring, failed or selected'), which distinguishes it from create_service_datasource and connect_datasource without opening either schema.

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

Usage Guidelines5/5

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

Explicitly routes the caller by payload type: full credentials declaration, auth for OAuth, no_credentials for a public service, or a complete mcp declaration for MCP servers, and warns never to mix them. It names the redirect target when this tool is wrong (connector_republish_required with publish_module_version) and the terminal refusal (already_connected).

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