Self-Documenting AI Agents: OpenAPI 3.0 Spec Generation for MCP Tools

Self-Documenting AI Agents: OpenAPI 3.0 Spec Generation for MCP Tools

MCP developers building onchain AI agents often hit the same wall: your Claude agent can reason brilliantly, but it has no idea what tools are actually available, what parameters they expect, or how to authenticate. WAIaaS solves this by combining 45 MCP tools with a live OpenAPI 3.0 spec — so your agent always has accurate, machine-readable documentation for every wallet, transaction, and DeFi action it can take.

Why This Actually Matters

When you wire an AI agent to onchain infrastructure, documentation isn't a nice-to-have — it's load-bearing. If your agent guesses at parameter names, misunderstands authentication requirements, or doesn't know which networks are supported, it makes mistakes with real money. The combination of MCP tooling and a live OpenAPI spec means two things: Claude gets structured tool definitions through the MCP protocol, and any HTTP client (including other agents, scripts, or dashboards you build) can discover the full API surface automatically. Both layers stay in sync because they're generated from the same codebase.

One Line in Your Config

Let's start with the fastest path. Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "waiaas": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_SESSION_TOKEN": "wai_sess_<your-token>",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

That's it. Restart Claude Desktop and your agent now has access to 45 MCP tools covering wallet management, token transfers, DeFi actions, NFT operations, and x402 HTTP payment — all authenticated, all policy-governed, all with typed parameters that Claude can introspect before calling them.

The MCP server package is @waiaas/mcp on npm, transport is stdio, and tools are served with full schema definitions so Claude understands input shapes without guessing.

What the 45 Tools Actually Cover

The tool list isn't just send-token and check-balance. Here's the full scope across categories:

Wallet & balance: get-wallet-info, get-address, get-balance, get-assets, get-nonce, connect-info

Transactions: send-token, send-batch, sign-transaction, sign-message, simulate-transaction, get-transaction, list-transactions, list-incoming-transactions, get-incoming-summary

DeFi: action-provider, get-defi-positions, get-health-factor, approve-token, list-offchain-actions

Account Abstraction: build-userop, sign-userop, encode-calldata, call-contract

NFT: get-nft-metadata, list-nfts, transfer-nft

Protocols: hyperliquid, polymarket, resolve-asset, get-tokens, get-provider-status

Sessions & auth: list-sessions, list-credentials, get-policies

ERC standards: erc8004-get-agent-info, erc8004-get-reputation, erc8004-get-validation-status, erc8128-sign-request, erc8128-verify-signature

WalletConnect: wc-connect, wc-disconnect, wc-status

Utility: get-rpc-proxy-url, x402-fetch, get-transaction (with full hash resolution)

When Claude sees simulate-transaction in the tool list, it knows it can dry-run before executing. When it sees get-health-factor, it understands DeFi lending positions are trackable. The schema-first design means Claude reasons about what's possible before committing to an action.

The OpenAPI Layer: For Everything Else

The MCP interface handles Claude. But you probably also have scripts, dashboards, or other agents that talk to WAIaaS over HTTP. That's where the OpenAPI 3.0 spec comes in.

WAIaaS auto-generates a live OpenAPI spec at /doc and serves an interactive Scalar API reference at /reference. Both stay current with the actual implementation — 39 REST API route modules feeding a single spec.

# Download the OpenAPI 3.0 spec
curl http://127.0.0.1:3100/doc -o openapi.json

# View the interactive reference in your browser
open http://127.0.0.1:3100/reference

The interactive UI at /reference is useful during development: you can see every endpoint, its authentication requirement, request schema, and response shape without reading source code. When you're building a policy configuration or debugging a DeFi action response, this is significantly faster than grepping through documentation.

The spec is also what you'd feed to another agent or code generator. If you're building a second AI agent that orchestrates WAIaaS over REST rather than MCP, point it at /doc and it has a complete, accurate description of the API surface.

Authentication Is Part of the Schema

One thing that trips up developers building multi-agent systems: WAIaaS uses three distinct authentication methods, and the OpenAPI spec documents which endpoints require which.

# masterAuth — create wallets, manage sessions, set policies
-H "X-Master-Password: my-secret-password"

# sessionAuth — AI agent operations (transactions, balance, DeFi)
-H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..."

# ownerAuth — human approval for high-value transactions
-H "X-Owner-Signature: <ed25519-or-secp256k1-signature>"
-H "X-Owner-Message: <signed-message>"

In the MCP context, the session token you put in WAIAAS_SESSION_TOKEN handles all agent-facing operations. The session was created by a human operator using masterAuth — the agent never sees the master password. This separation is intentional: the agent has a scoped credential with policy limits, not root access to the wallet system.

Setting Up a Multi-Wallet MCP Configuration

For more sophisticated setups — say, a trading agent and a separate Solana wallet agent — you can run multiple named MCP servers pointing at the same WAIaaS daemon:

{
  "mcpServers": {
    "waiaas-trading": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c47d6-51ef-7f43-a76b-d50e875d95f4",
        "WAIAAS_AGENT_NAME": "trading-agent",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    },
    "waiaas-solana": {
      "command": "npx",
      "args": ["-y", "@waiaas/mcp"],
      "env": {
        "WAIAAS_BASE_URL": "http://127.0.0.1:3100",
        "WAIAAS_AGENT_ID": "019c4cd2-86e8-758f-a61e-9c560307c788",
        "WAIAAS_AGENT_NAME": "solana-wallet",
        "WAIAAS_DATA_DIR": "~/.waiaas"
      }
    }
  }
}

Each MCP server instance has its own session token scoped to a specific wallet. Claude sees both as separate tool namespaces and can reason about which wallet to use for which operation — all documented through the MCP tool schemas.

What Claude Can Actually Do After This

Here's what the interaction looks like in practice once MCP is connected:

User: "Check my wallet balance"
→ Claude calls get_balance tool → returns balance

User: "Swap 0.1 SOL for USDC on Jupiter"
→ Claude calls execute_action tool with jupiter-swap provider

User: "Show my DeFi positions across all protocols"
→ Claude calls get_defi_positions tool → returns lending/staking positions

The Jupiter swap call hits one of 15 integrated DeFi protocol providers — including Aave v3, Across, Drift, Hyperliquid, Jito staking, Jupiter swap, Kamino, Lido staking, LI.FI, Pendle, Polymarket, XRPL DEX, and 0x swap, among others. Claude doesn't need to know the protocol-specific parameters because the tool schema defines them.

Before any transaction executes, the 7-stage pipeline processes it: validate → auth → policy → wait → execute → confirm. If a policy blocks it, Claude gets back a structured error:

{
  "error": {
    "code": "POLICY_DENIED",
    "message": "Transaction denied by SPENDING_LIMIT policy",
    "domain": "POLICY",
    "retryable": false
  }
}

That error code is something Claude can reason about — it knows the transaction was blocked by a spending limit, not a network error, and can explain that to the user or suggest alternatives.

Quick Start: From Zero to MCP Tools in 5 Steps

Step 1: Install the CLI and initialize

npm install -g @waiaas/cli
waiaas init
waiaas start

Step 2: Create wallets and sessions in one command

waiaas quickset --mode mainnet

This creates wallets and MCP sessions. The output includes the MCP config JSON.

Step 3: Register with Claude Desktop automatically

waiaas mcp setup --all

Step 4: Verify the OpenAPI spec is live

curl http://127.0.0.1:3100/doc -o openapi.json
# Then open http://127.0.0.1:3100/reference in your browser

Step 5: Set a spending policy so the agent has safe limits

curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 100,
      "notify_max_usd": 500,
      "delay_max_usd": 2000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'

Restart Claude Desktop and ask it to check your balance.

The Self-Documenting Part

The reason this system is "self-documenting" isn't marketing language — it's a practical property. The 45 MCP tools and the 39 REST API route modules both derive their schemas from the same source. When WAIaaS adds a new capability, the OpenAPI spec at /doc updates automatically, the interactive reference at /reference reflects it, and the MCP tool definitions that Claude receives are current.

For developers building on top of WAIaaS — whether you're writing an agent orchestration layer, a monitoring dashboard, or a second AI system that talks to WAIaaS over HTTP — you always have an accurate map of the territory. You don't maintain separate documentation, you don't discover parameter mismatches at runtime, and you don't need to read source code to understand what's available.

That's the core value proposition for MCP developers specifically: you get 45 typed, schema-defined tools that Claude can introspect, plus a live HTTP API that any other client can discover — all from a single self-hosted daemon you control.

What's Next

If you want to explore the policy engine in depth — setting spending limits, token whitelists, and DeFi-specific controls like maximum leverage — the 21 policy types give you fine-grained control over what your agent can and can't do autonomously. The Docker deployment path is also worth looking at if you're running this in a persistent server environment rather than locally.

The full codebase, including the MCP package and all 15 DeFi protocol providers, is at https://github.com/minhoyoo-iotrust/WAIaaS. More documentation and the official site are at https://waiaas.ai.