Docs/Quick Start

Quick Start

Add MACAW to your AI application. This guide shows integration with OpenAI—the same pattern works for Anthropic, LangChain, and MCP.

Prerequisites

Python	3.9 or later
MACAW Account	Sign up at console.macawsecurity.ai

1. Install

Download the SDK from the Console. The package includes your workspace configuration.

aDownload from Console

bUnzip and install

bash

# Unzip the download
unzip macaw-client-*.zip

# Install the package
pip install ./macaw-client-*/*.whl

2. Integrate

Option A: Adapter (Recommended)

Use a drop-in adapter. Your existing code works unchanged—just swap the import.

python

from macaw_adapters.openai import SecureOpenAI

client = SecureOpenAI(app_name="my-app")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

Option B: Direct Client

Use MACAWClient directly for tool invocations and custom integrations.

python

from macaw_client import MACAWClient

client = MACAWClient(app_name="my-app")
client.register()

result = client.invoke_tool("calculator", {
    "operation": "add",
    "a": 5,
    "b": 3
})

client.unregister()

3. Verify

Run a test call. If configured correctly, you'll see the response and the invocation will appear in your Console audit log.

The call is signed, policy-checked, and logged—without changing your application code.

python

from macaw_adapters.openai import SecureOpenAI

client = SecureOpenAI(app_name="quickstart-test")

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Say hello"}]
)

print(response.choices[0].message.content)
# Output: Hello! How can I help you today?

# Check Console → Audit Logs to see the signed invocation

How It Works

Your App

signs request

invocation

Endpoint

verifies + enforces

Sign

cryptographic

Verify

identity

Evaluate

policy

Execute

or deny

The receiver verifies independently. A compromised caller cannot forge signatures or bypass policy.

Policy Enforcement

Requests that violate policy are rejected before execution. The denial includes the reason, which is also logged for audit.

python

from macaw_client import MACAWClient, PermissionDenied

client = MACAWClient(app_name="my-app")
client.register()

try:
    # Policy denies access to /etc/passwd
    client.invoke_tool("file/read", {"path": "/etc/passwd"})
except PermissionDenied as e:
    print(f"Blocked: {e.reason}")
    # Blocked: Policy denies file/read for path=/etc/passwd

Other Frameworks

The same pattern works for other AI frameworks. Change the import, keep your code.

python

# Anthropic
from macaw_adapters.anthropic import SecureAnthropic

client = SecureAnthropic(app_name="my-app")
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

python

# LangChain
from macaw_adapters.langchain.openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4")
response = llm.invoke("Hello")

# Cleanup when done
from macaw_adapters.langchain.agents import cleanup
cleanup()

Next Steps

Hello World Tutorial

Step-by-step first secured call

MAPL Policies

Define what agents can do

MACAWClient API

Full SDK reference

Framework Guides

OpenAI, Anthropic, LangChain, MCP