What causes "failed to list MCP prompts: status code %d" in charmbracelet/crush?

Map the status: 401/403 → re-authenticate; 404 → check workspace ID and API version; 5xx → server logs.

failed to list MCP prompts: status code %d

Error message

failed to list MCP prompts: status code %d

What it means

ListMCPPrompts expects HTTP 200 from /workspaces/{id}/mcp/prompts. A non-200 response raises 'failed to list MCP prompts: status code %d'; the body is not surfaced, only the numeric status.

Source

Thrown at internal/client/config.go:331

	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("failed to read MCP resource: status code %d", rsp.StatusCode)
	}
	var contents []MCPResourceContents
	if err := json.NewDecoder(rsp.Body).Decode(&contents); err != nil {
		return nil, fmt.Errorf("failed to decode MCP resource: %w", err)
	}
	return contents, nil
}

func (c *Client) ListMCPPrompts(ctx context.Context, id string) ([]proto.MCPPrompt, error) {
	rsp, err := c.get(ctx, fmt.Sprintf("/workspaces/%s/mcp/prompts", id), nil, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to list MCP prompts: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("failed to list MCP prompts: status code %d", rsp.StatusCode)
	}
	var prompts []proto.MCPPrompt
	if err := json.NewDecoder(rsp.Body).Decode(&prompts); err != nil {
		return nil, fmt.Errorf("failed to decode MCP prompts: %w", err)
	}
	return prompts, nil
}

// GetMCPPrompt retrieves a prompt from a named MCP server.
func (c *Client) GetMCPPrompt(ctx context.Context, id, clientID, promptID string, args map[string]string) (string, error) {
	rsp, err := c.post(ctx, fmt.Sprintf("/workspaces/%s/mcp/get-prompt", id), nil, jsonBody(struct {
		ClientID string            `json:"client_id"`
		PromptID string            `json:"prompt_id"`
		Args     map[string]string `json:"args"`
	}{ClientID: clientID, PromptID: promptID, Args: args}), http.Header{"Content-Type": []string{"application/json"}})
	if err != nil {
		return "", fmt.Errorf("failed to get MCP prompt: %w", err)
	}

View on GitHub (pinned to 7944b8e522)

Solutions

Map the status: 401/403 → re-authenticate; 404 → check workspace ID and API version; 5xx → server logs.
Confirm the client and server API versions match.
Ensure configured MCP servers are healthy so the backend query succeeds.
Retry transient 502/503 with backoff.

Example fix

// before
prompts, err := client.ListMCPPrompts(ctx, id)
// after
prompts, err := client.ListMCPPrompts(ctx, id)
if err != nil && strings.Contains(err.Error(), "status code 401") {
    if err := refreshSession(ctx); err != nil { return nil, err }
    prompts, err = client.ListMCPPrompts(ctx, id)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure an authenticated session before listing
if sessionExpired() {
    if err := relogin(ctx); err != nil {
        return errors.New("authentication required before listing MCP prompts")
    }
}

Try / catch

prompts, err := client.ListMCPPrompts(ctx, id)
if err != nil {
    var code int
    if n, _ := fmt.Sscanf(err.Error(), "failed to list MCP prompts: status code %d", &code); n == 1 {
        switch {
        case code == 401 || code == 403:
            err = retryAfterAuth(ctx)
        case code >= 500:
            err = retryWithBackoff(ctx)
        case code == 404:
            return nil, fmt.Errorf("prompts endpoint unavailable — check server version and workspace ID")
        }
    }
    if err != nil { return nil, err }
}

Prevention

Refresh auth tokens before they expire in long-running sessions.
Verify the server supports the prompts endpoint (version check).
Retry 5xx and 502/503 with exponential backoff.
Validate workspace IDs before calls to avoid 404s.

When it happens

Trigger: 401/403 (expired or missing auth), 404 (bad workspace ID or server lacking this route), 500 (backend failed to query MCP servers), 502 from a proxy.

Common situations: Auth token expiry during long sessions; older Coder server without the prompts endpoint; MCP server misconfiguration making the backend return 500.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/cb83d8a1151d70d9. Report an issue: GitHub.