Create an MCP tool with secrets

Secrets are sensitive strings like passwords, api-keys, or other tokens that grant access to a protected resource or API. Although you could use secrets to transfer any static information to your tool, such as a parameter needed to call a remote API.

Why use secrets in your tools?

Secrets enable you to securely deploy a function that requires sensitive information at runtime. And while these can be consumed directly from the runtime environment inside your tool function, this becomes very inconvenient, expensive, hard to maintain, and insecure when deploying at scale.

For example, if your tool requires an API key to use an external service, but only after doing some computationally expensive work, you need to ensure that the API key is present before the computationally expensive work is done. The function below would fail if the API key is not present.

import os
 
def my_tool(task: str) -> str:
    result = expensive_computation(task)
 
    API_KEY = os.getenv("API_KEY")
 
    # The line below will fail if the API key is not present
    success = upload_result_to_service(result, API_KEY)
 
    if success:
        return "Result uploaded successfully"
    else:
        return "Failed to upload result"

We can work around this by carefully checking for the API key before doing the computationally expensive work, of course, but this is error prone and difficult to maintain, and you may only become aware of the issue after deploying multiple instances of your server.

Arcade provides a way to securely store and access secrets inside your tools in a way that is easy to manage across multiple instances of your servers, and that will prevent the tool from running if the secret is not provided. In this guide, you’ll learn how to use secrets in your custom Arcade tools.

MY_SECRET_KEY="my-secret-value"

mv .env.example .env

export MY_SECRET_KEY="my-secret-value"

@app.tool(
    requires_secrets=["SECRET_KEY"],  # declare we need SECRET_KEY
)
def use_secret(context: Context) -> str:
    """Read SECRET_KEY from context and return a masked confirmation string."""
    try:
        value = context.get_secret("SECRET_KEY")
        masked = value[:2] + "***" if len(value) >= 2 else "***"
        return f"Got SECRET_KEY of length {len(value)} -> {masked}"
    except Exception as e:
        return f"Error getting secret: {e}"

Key Concepts

• Secure Access Secrets are accessed through context, not imported directly
• Environment Integration Works with both environment variables and .env files
• Error Handling Always handle the case where a secret might be missing
• Masking Never expose full secret values in logs or return values
• Declaration Use requires_secrets to make dependencies explicit

Example Code

Environment Variables

SECRET_KEY="supersecret"

#!/usr/bin/env python3
import sys
 
from arcade_mcp_server import Context, MCPApp
 
# Create the MCP application
app = MCPApp(
    name="secrets_example",
    version="1.0.0",
    instructions="Example server demonstrating secrets usage",
)
 
 
@app.tool(
    requires_secrets=["SECRET_KEY"],  # declare we need SECRET_KEY
)
def use_secret(context: Context) -> str:
    """Read SECRET_KEY from context and return a masked confirmation string."""
    try:
        value = context.get_secret("SECRET_KEY")
        masked = value[:2] + "***" if len(value) >= 2 else "***"
        return f"Got SECRET_KEY of length {len(value)} -> {masked}"
    except Exception as e:
        return f"Error getting secret: {e}"
 
 
if __name__ == "__main__":
    # Check if stdio transport was requested
    transport = "stdio" if len(sys.argv) > 1 and sys.argv[1] == "stdio" else "http"
 
    print(f"Starting {app.name} v{app.version}")
    print(f"Transport: {transport}")
 
    # Run the server
    app.run(transport=transport, host="127.0.0.1", port=8000)

Run your MCP server

uv run secrets.py http

uv run secrets.py stdio