Skip to main content
Glama
Datris MCP Server

Datris MCP Server

create_tap_secret

Create or update a credential secret and inject its fields as environment variables into a tap's Python script at runtime, so taps can authenticate to APIs or databases.

Instructions

Create or update a secret for a tap to use. The secret's fields are injected as environment variables into the tap's Python script at runtime. Use this before create_tap when the tap needs credentials (API key, DB password, etc.). FIRST call list_tap_secrets to check whether a suitable secret already exists — if so, reuse it instead of creating a duplicate. By default, fails if a secret with this name already exists — pass overwrite=true to replace it (ask the user first). Agents can only overwrite secrets that were also created by an agent (tagged _type=tap); secrets owned by a human user must be updated via the UI. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status pending_approval with an approvalId. Tell the user it is waiting for approval in Datris, then poll get_approval with that id (pause with wait_seconds between polls) — do not re-issue the action.

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": {
      "name": "<name>",
      "fields": "<fields>"
    },
    "name": "create_tap_secret"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesSecret name. Must not use reserved AI-slot names (anthropic, openai, azure, grok, ollama, embedding, ai-primary, codegen). Convention: lowercase, hyphenated, e.g. 'stripe-api-key'.
fieldsYesKey-value fields. Each key becomes an env var name in the tap script; e.g., {"apiKey": "sk_..."} is read as os.environ['apiKey'].
reasonNoOptional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
overwriteNoIf true, replace an existing secret with the same name. Default false (fails on collision). Only tap-typed secrets can be overwritten by an agent.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does so: it discloses the runtime env-var injection, that the default fails on name collision, that overwrite replaces a secret, that agents may only overwrite agent-tagged (_type=tap) secrets while human-owned ones require the UI, and the full approval flow including the pending_approval status and approvalId polling with get_approval.

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 the core action and orders guidance logically (purpose, prerequisite listing, overwrite rule, approval flow). It is dense but long, with several lengthy sentences; almost every clause carries operational value, though the approval paragraph could be tightened.

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 mutation tool with no annotations and no output schema, the description still explains the write effect, the collision behavior, ownership restrictions, and the exact approval/pending_approval response. An agent has everything needed to call it correctly and handle the approval branch.

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 meaning beyond the schema for overwrite (ask the user first, agent-owned restriction) and backfills the approval context around the call. It does not add much on name/fields, but the overwrite semantics genuinely extend the schema's one-line description.

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 specific verb and resource ("Create or update a secret for a tap") and immediately distinguishes its effect by explaining the fields become environment variables in the tap script. It also implicitly separates itself from list_tap_secrets and delete_tap_secret by naming the listing tool as a prerequisite and by defining this as an upsert.

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?

Gives explicit when-to-use ("Use this before create_tap when the tap needs credentials") and a named alternative workflow ("FIRST call list_tap_secrets ... reuse it instead of creating a duplicate"). It also states the overwrite condition and tells the agent to ask the user first, covering the main decision an agent faces.

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

Deploy Server

Other Tools