Building with the Python SDK

This guide covers building tools, agent workflows, and MCP servers with AgentSecrets, ensuring credentials remain protected from process memory and LLM prompt contexts.

Deployment Context: Currently, AgentSecrets operates locally on your development machine or server environment, where the local CLI and keychain-auth daemon broker secret resolution. Fully managed cloud workspace delegation for end-users is on the future product roadmap.

Using Official Vendor SDKs (Interception & Credential Helper)

When building applications with standard Python client libraries (stripe, openai, anthropic, langchain), initialize init() at startup and supply credential.<KEY> placeholders to your client configurations:

import stripe
from agentsecrets import init, credential

# 1. Initialize interception at application startup
init()

# 2. Configure official libraries with zero-knowledge credentials
stripe.api_key = credential.STRIPE_SECRET_KEY

# 3. Use standard SDK methods
def get_account_balance():
    return stripe.Balance.retrieve()

def create_payment_charge(amount: int, currency: str = "usd", source: str = "tok_visa"):
    return stripe.Charge.create(
        amount=amount,
        currency=currency,
        source=source
    )

How it works:

• Application memory holds only the placeholder reference string ("AS_SECRET_STRIPE_SECRET_KEY").
• When an outgoing API call is made, the interceptor routes the request through the local proxy.
• Real keys are resolved by keychain-auth and injected directly into the outbound TLS stream at the network transport boundary.

Direct Proxy Calls via AgentSecrets Client

For custom API endpoints or raw HTTP communication without third-party libraries, use the AgentSecrets context manager:

from agentsecrets import AgentSecrets

class PaymentService:
    def __init__(self, project: str = "payments"):
        self.project = project

    def get_balance(self):
        with AgentSecrets(project=self.project) as client:
            response = client.call(
                "https://api.stripe.com/v1/balance",
                bearer="STRIPE_KEY"
            )
            return response.json()

Building Zero-Knowledge MCP Servers

To build Model Context Protocol (MCP) tools for Claude Desktop or Cursor:

1. Scaffold from template:

   git clone https://github.com/The-17/zero-knowledge-mcp
   cd zero-knowledge-mcp

2. Implement tools using init() or client.call(): Tools accept and pass key names. LLM assistants invoke tools and receive responses without the credential ever entering the prompt context window.

Unit Testing with MockAgentSecrets

Test your tools and agent workflows offline without needing a running proxy daemon:

from agentsecrets.testing import MockAgentSecrets
from agentsecrets.client import Response

def test_payment_balance():
    mock = MockAgentSecrets()
    mock.set_response(
        "https://api.stripe.com/v1/balance",
        Response(
            status_code=200,
            body='{"object": "balance", "available": [{"amount": 420000, "currency": "usd"}]}',
            headers={}
        )
    )

    # Test execution
    response = mock.call("https://api.stripe.com/v1/balance", bearer="STRIPE_KEY")
    result = response.json()

    assert result["available"][0]["amount"] == 420000
    assert len(mock.calls) == 1
    assert mock.calls[0].bearer == "STRIPE_KEY"
    assert mock.calls[0].url == "https://api.stripe.com/v1/balance"
    # No plaintext credentials exist in test traces