# AgentBureau: The Notary for the agentic age

Website: https://agentbureau.de/

Github: https://github.com/JustinGuese/AgentBureau-402-embodiment-as-a-service

[![smithery badge](https://smithery.ai/badge/guese-justin/AgentBureau)](https://smithery.ai/servers/guese-justin/AgentBureau)

AgentBureau provides the legal and physical infrastructure for AI agents to operate within the German jurisdiction. We bridge the gap between digital intelligence and real-world action by providing "Embodiment-as-a-Service."

Through our API, agents can perform legally binding actions—like sending faxes, mailing physical letters, issuing invoices, forming entire companies (GmbH/UG), handling tax compliance, and opening corporate bank accounts—without needing a bank account, a physical address, or a human identity.

## The Core Mechanism: x402 Payment Gating

AgentBureau uses the **x402 protocol**, an agent-native authentication method where **payment is authentication**.

1. **No API Keys**: Agents don't need to manage secrets or create accounts.
2. **Permissionless**: Settlement happens on-chain (USDC on Base L2).
3. **Machine-Readable**: Every request returns structured metadata for autonomous handling of 402 "Payment Required" challenges.

---

## Available Services

| Service              | Tool Name              | Price (USDC) | Delivery Method      |
| :------------------- | :--------------------- | :----------- | :------------------- |
| **Digital Invoice**  | `send_german_invoice`  | 5.00         | via Lexoffice        |
| **Physical Letter**  | `send_letter`          | 3.00         | via Pingen (Germany) |
| **Programmatic Fax** | `send_fax`             | 1.00         | via Telnyx           |
| **GmbH Formation**   | `form_german_company`  | 3,000.00\*   | HITL Concierge       |
| **UG Formation**     | `form_german_company`  | 1,500.00\*   | HITL Concierge       |
| **Bank Account**     | `open_bank_account`    | 500.00       | FinTech Integration  |
| **VAT Registration** | `register_vat`         | 500.00       | Tax Portal Sync      |
| **VAT Return**       | `submit_vat_return`    | 100.00       | Monthly/Quarterly    |
| **Annual Filing**    | `create_annual_filing` | 200.00       | Bundesanzeiger       |
| **Debt Collection**  | `collect_debt`         | 50.00        | Inkasso Automation   |
| **EU Presence**      | `eu_presence_bundle`   | 5,000.00     | Full Legal Shield    |

_\*Formation fees exclude the required share capital (Stammkapital), which is handled via a secure escrow workflow._

---

## Spend Controls (Mandates)

**The problem:** a funded agent wallet has exactly one limit — its balance. A retry loop, a
prompt injection or a mis-parsed instruction turns that into an unbounded invoice, and
on-chain settlement is final.

**A mandate** is a signed, scope-limited, expiring spending authorization for one wallet.
It is the x402-native equivalent of an [AP2](https://agentbureau.de/agent-spend-controls)
mandate — it answers *which actor*, *what scope*, *what limits*, *under what conditions* —
bound by an EIP-191 signature. Creating, reading, revoking and auditing one is **free** and
needs no account: the signature is the authorization, exactly as the x402 payment is the
authentication everywhere else.

| Dimension | What it caps |
| :--- | :--- |
| `per_call_cap_usdc` | The most a single call may cost |
| `daily_cap_usdc` | Spend per UTC calendar day |
| `monthly_cap_usdc` | Spend per UTC calendar month |
| `total_cap_usdc` | Lifetime spend under this mandate |
| `allowed_paths` | Allowlist of services; everything else is refused regardless of price |
| `not_before` / `expires_at` | Validity window, with revocation at any time |

**The part that matters — denied *before* you pay.** Attach `X-MANDATE-ID` to a priced call
and the gateway evaluates your caps before it issues the x402 challenge. An over-budget
agent gets `403` and an `X-POLICY-DENIED` header naming the breached limit; it never
receives a payment request, so it never spends.

```bash
curl -X POST https://agentbureau-api.datafortress.cloud/v1/invoices \
     -H "X-MANDATE-ID: 0x5881…" -H "Content-Type: application/json" -d '{…}'

HTTP/1.1 403 Forbidden
X-POLICY-DENIED: per_call_cap_exceeded
```

Omit the header and caps still apply, but only after the payment settles — the call is
refused and the payment is queued for refund. Always send the header.

Alongside it: `GET /v1/mandates/{id}/status` returns remaining budget (also exposed as the
read-only MCP tool `check_spend_budget`, so an agent can check mid-run), and
`GET /v1/mandates/{id}/audit?format=csv` exports the spend ledger, authorized by a
signature from the spending wallet and deliberately excluding request payloads so customer
PII stays out of the audit path.

> [!NOTE]
> AgentBureau implements the AP2 mandate *model* on the x402 rail. It does **not** accept
> AP2 mandates issued on card or bank rails — that is roadmap, not shipped.

Try it: [agentbureau.de/agent-spend-controls](https://agentbureau.de/agent-spend-controls) ·
Docs: [Spend Mandates](https://agentbureau.de/docs/for-agents/spend-mandates),
[Policy Denied (403)](https://agentbureau.de/docs/reference/policy-denied) ·
Examples: [curl](./examples/curl/mandate.sh), [Python](./examples/python/mandate.py),
[TypeScript](./examples/typescript/mandate.ts)

---

## Runnable Code Examples

We provide a comprehensive 6×4 matrix of runnable scripts demonstrating how to integrate AgentBureau services across various languages and frameworks. These examples handle the full x402 flow: **Challenge → Payment → Retry**.

### Integration Matrix

| Client / Language     |                     Fax                      |                       Letter                       |                       Invoice                        |                      GmbH                      |
| :-------------------- | :------------------------------------------: | :------------------------------------------------: | :--------------------------------------------------: | :--------------------------------------------: |
| **cURL / Bash**       |       [fax.sh](./examples/curl/fax.sh)       |       [letter.sh](./examples/curl/letter.sh)       |       [invoice.sh](./examples/curl/invoice.sh)       |       [gmbh.sh](./examples/curl/gmbh.sh)       |
| **Python (httpx)**    |      [fax.py](./examples/python/fax.py)      |      [letter.py](./examples/python/letter.py)      |      [invoice.py](./examples/python/invoice.py)      |      [gmbh.py](./examples/python/gmbh.py)      |
| **TypeScript (viem)** |    [fax.ts](./examples/typescript/fax.ts)    |    [letter.ts](./examples/typescript/letter.ts)    |    [invoice.ts](./examples/typescript/invoice.ts)    |    [gmbh.ts](./examples/typescript/gmbh.ts)    |
| **LangChain**         |    [fax.py](./examples/langchain/fax.py)     |    [letter.py](./examples/langchain/letter.py)     |    [invoice.py](./examples/langchain/invoice.py)     |    [gmbh.py](./examples/langchain/gmbh.py)     |
| **Claude Tool Use**   | [fax.py](./examples/claude-tool-use/fax.py)  | [letter.py](./examples/claude-tool-use/letter.py)  | [invoice.py](./examples/claude-tool-use/invoice.py)  | [gmbh.py](./examples/claude-tool-use/gmbh.py)  |
| **OpenAI Responses**  | [fax.py](./examples/openai-responses/fax.py) | [letter.py](./examples/openai-responses/letter.py) | [invoice.py](./examples/openai-responses/invoice.py) | [gmbh.py](./examples/openai-responses/gmbh.py) |

Plus **spend mandates**, which are not a service but a cap across all of them —
[mandate.sh](./examples/curl/mandate.sh) ·
[mandate.py](./examples/python/mandate.py) ·
[mandate.ts](./examples/typescript/mandate.ts). These three need no USDC and send no
transaction, so they run end to end on an empty wallet.

### How to Run the Examples

1. **Navigate to the examples directory**:
   ```bash
   cd examples
   ```
2. **Configure your environment**:
   ```bash
   cp .env.example .env
   # Edit .env with your PRIVATE_KEY (Base network) and RPC_URL
   ```
3. **Install and Run**:
   - **Python**: `pip install -r <folder>/requirements.txt && python <folder>/<file>.py`
   - **TypeScript**: `cd typescript && npm install && npx ts-node <file>.ts`
   - **Shell**: `bash curl/<file>.sh`

---

## MCP Integration

AgentBureau is **MCP Native**, served over **Streamable HTTP** at `https://agentbureau-api.datafortress.cloud/mcp`. The server exposes **12 tools** (one per priced REST endpoint) and **8 prompts** (parameterised workflow playbooks).

### Quickstart (30 seconds)

The fastest path is the [Smithery one-click install](https://smithery.ai/servers/guese-justin/AgentBureau) for Claude Desktop, ChatGPT, Cursor, or Windsurf. No API key, no parameters — payment is handled per-call via x402.

For direct config, drop this into `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agentbureau": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://agentbureau-api.datafortress.cloud/mcp"]
    }
  }
}
```

Then ask your agent something like _"Send a physical letter via AgentBureau to the Berlin Finanzamt"_ — it will surface the 402 payment metadata, pay USDC on Base, and retry automatically.

### Prompts (workflow playbooks)

| Prompt | Use Case |
| :--- | :--- |
| `incorporate_german_company` | Form a UG (1 EUR capital) or GmbH (25k EUR) end-to-end |
| `establish_eu_presence` | Bundle: formation + VAT + registered office (5,000 USDC) |
| `send_schriftform_letter` | Legally-binding physical letter (BGB §126 compliant) |
| `fax_german_authority` | Fax to Finanzamt / Handelsregister / Amtsgericht |
| `bill_german_customer` | GoBD-compliant invoice with auto VAT calculation |
| `submit_monthly_vat` | Umsatzsteuervoranmeldung via ELSTER |
| `collect_unpaid_invoice` | Hand off to licensed German Inkasso firm |
| `delegate_authority` | Issue Vollmacht (notarized + Apostille optional) |

You can use the AgentBureau connector to "handle the German bureaucracy" with direct instructions:

- **Establish Legal Personality**: "Incorporate a new German UG for my AI startup via the HITL concierge."
- **Bypass Analog Bureaucracy**: "Fax this address verification document to the Berlin commercial register to satisfy Schriftform requirements."
- **Automate Financial Operations**: "Generate a compliant German invoice for 5,000 EUR and submit my quarterly VAT return."
- **Manage Corporate Compliance**: "Create the annual filing for my company in the Bundesanzeiger."
- **Secure Physical Presence**: "Send a physical, legally-binding letter to this recipient in Germany."
- **Scale Institutional Agency**: "Register my agent-owned entity for a VAT ID and open a SEPA-compliant bank account."

### Ways to Connect

**1. Smithery Gateway (one-click for Claude / ChatGPT / Cursor / Windsurf)**

Install from the [Smithery listing](https://smithery.ai/servers/guese-justin/AgentBureau) — Smithery proxies through `agentbureau--guese-justin.run.tools` and handles transport negotiation for clients that don't yet speak Streamable HTTP natively.

**2. Direct connection (clients that support remote MCP)**

```json
{
  "mcpServers": {
    "agentbureau": {
      "url": "https://agentbureau-api.datafortress.cloud/mcp"
    }
  }
}
```

**3. `mcp-remote` bridge (older clients)**

```json
{
  "mcpServers": {
    "agentbureau": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agentbureau-api.datafortress.cloud/mcp"
      ]
    }
  }
}
```

Authentication is per-call via the **x402 payment protocol** (USDC on Base) — no API key required.

---

## Website Development

This repository contains the source code for the [agentbureau.de](https://agentbureau.de) website and documentation.

### Tech Stack

- **Framework**: Astro 5 (Starlight for docs)
- **Styling**: Tailwind CSS v4
- **Interactive Islands**: React

### Getting Started

1. **Install dependencies**:
   ```bash
   npm install
   ```
2. **Start development server**:
   ```bash
   npm run dev
   ```
3. **Build for production**:
   ```bash
   npm run build
   ```

### Analytics & Conversion Tracking

Meta Pixel + Google Analytics 4 are wired into `src/layouts/Landing.astro`, **consent-gated** (neither loads until the user accepts cookies via `CookieBanner.astro`). Events fire to both platforms in parallel:

- **Lead / Schedule / Contact / CompleteRegistration** — CTA, `cal.com`, `mailto:`/`tel:`, and Compliance Scanner interactions (via `trackConversion(name, params)`, matched locale-independently by `href`).
- **E-commerce funnel** (from the `/playground` widget, via `window.trackEcommerce(metaEvent, params)`):
  - `AddToCart` / `add_to_cart` — user runs the **demo (sim)** or completes a **testnet** request.
  - `Purchase` / `purchase` — user completes a **real mainnet USDC payment**, with the on-chain `value` and tx hash.

Meta uses CamelCase event names and GA4 uses snake_case for the same concept; `trackEcommerce` maps between them. Only browser-based playground payments are tracked — headless agents calling the live API have no browser and would require server-side tracking (not yet implemented). See `AGENTS.md` for the full event table and conventions.

## Documentation

Full documentation, including legal frameworks (ZAG exemption, Störerhaftung), detailed API references, and agent-specific integration guides, is available at [/docs](https://agentbureau.de/docs).

---

## Marketing & Community

AgentBureau is being integrated into the following agentic registries and hubs:

- **MCP Registries**: [Smithery](https://smithery.ai/), [Glama](https://glama.ai/mcp), [Awesome-MCP](https://github.com/punkpeye/awesome-mcp)
- **Agent Ecosystems**: [LangChain Hub](https://smith.langchain.com/hub), [CrewAI Tools](https://docs.crewai.com/core-concepts/Tools/)
- **Agentic Economy**: [Coinbase Developer Platform](https://www.coinbase.com/developer-platform), [Base Ecosystem](https://warpcast.com/~/channel/base)