---
title: "get_credential Reference | Gazebo Docs"
description: "Full reference for the get_credential MCP tool — parameters, response format, error handling, and usage patterns."
url: "https://gazebohq.com/docs/mcp/get-credential"
---

> Documentation index: [llms.txt](https://gazebohq.com/docs/llms.txt). Markdown versions are available by appending `.md` to documentation page URLs.

The `get_credential` tool retrieves a plaintext credential from the Gazebo vault for a named service. Valid credential-retrieval attempts are audited, including policy denials and missing credentials. Authentication failures and malformed arguments do not create credential-access events. If audit persistence fails, no credential is released. The value is delivered to the MCP client/agent; do not persist it.

## Security boundary

The runtime receives the actual stored provider key, not a new per-call credential. Its host can retain the value, and MCP clients may place tool responses in model context. Use trusted runtimes and narrow provider permissions. Revoking Gazebo access stops new retrieval, not use of keys already retrieved.

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `service` | string | Yes | The service slug (e.g. `"stripe"`, `"github"`, `"vercel"`) |
| `method` | string | Yes | The HTTP method you intend to use the credential for (`"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`) |
| `key_name` | string | Required for OAuth; optional for manual agent tokens | The explicitly approved named credential. Only manual agent-token requests may omit it to retrieve the service's primary active credential. |

The `method` parameter is policy-enforced — declaring `"POST"` when you intend to make a write call is not optional. If your access profile doesn't permit `POST` on that service, the call is denied and logged.

This check governs retrieval using the declared method. Gazebo does not proxy or enforce the provider API call made afterward; the retrieved key's provider permissions still apply.

### MCP behavior hints

The display title is **Retrieve a service credential**. The tool advertises `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false` and `openWorldHint: false`: valid attempts add credential-access events, successful calls release a sensitive stored key, and no provider request is executed. These hints do not require a client to ask for confirmation and do not replace authentication, selected-key approval or release-policy checks.

## Success response

On success, `get_credential` returns the plaintext credential as a string:

```
get_credential({ service: "stripe", key_name: "api_key", method: "GET" })
→ "<scoped-service-credential>"
```

Use this value directly in your API call. Do not persist it; retrieve it again when needed.

## Denial response

If the agent is not permitted to use the declared method, the tool returns JSON text inside `result.content`, with `result.isError: true`:

```json
{
  "status": "denied",
  "service": "stripe",
  "method": "DELETE",
  "allowed_methods": ["GET", "POST"]
}
```

If the service itself is not allowed, the JSON text is `{ "status": "denied", "service": "stripe" }`.

**On denial, do not retry without user intervention.** Parse the response, tell the user what happened, and stop. There are no `reason` or `next_action` fields in these MCP responses.

## Not-found response

If no active credential matches the requested service/key, the tool returns JSON text with `result.isError: true`:

```json
{
  "status": "not_found",
  "service": "stripe",
  "key_name": null
}
```

`key_name` is the requested name when supplied, or `null` when omitted. Check that the credential exists and has not expired.

## Error table

| HTTP status | `status` field | Meaning |
|---|---|---|
| 200 | — | Credential returned as MCP text content |
| 200 | `denied` | Tool error: service not allowed, or declared method not permitted |
| 200 | `not_found` | Tool error: no active credential matches |
| 401 | — | Invalid or missing bearer token |
| 403 | — | Untrusted browser Origin; not a credential-policy denial |
| 500 | — | Internal error, including failed audit persistence; no credential released |

Invalid tool arguments return a JSON-RPC error (`-32602`), not a structured `status` outcome. The table describes MCP, not the separate REST API.

## Recommended usage pattern

```
1. get_identity()                           → confirm accessible services
2. get_credential({ service, method })      → fetch the credential
3. [make your API call using the credential]
4. list_audit_events({ service, limit: 1 }) → optionally confirm it was logged
```

Do not store the returned credential in memory beyond the scope of the current API call. Treat it as ephemeral.
