MCP Stack

Every tool RapBotRito can call lives in the Model Context Protocol stack housed under dapp/app/lib/mcp. The architecture focuses on three qualities:

1. Central registration — toolRegistry (dapp/app/lib/mcp/tools/index.ts) registers each tool once and decides whether it should even exist (e.g., send-crypto tools only load when AI_PRIVATE_KEY is set, Pinecone tools only when configured).
2. Layered authentication — The MCP HTTP route (dapp/app/api/mcp/route.ts) optionally enforces JWTs globally, while MCPDispatcher forces another verification for tools with requiresJwt.
3. Mode-aware exposure — getOpenAIToolSchemas (dapp/app/lib/llm/tool-bridge.ts) filters the registry based on the active chat mode, so rap battles, freestyle, and agent battles each receive different tool manifests.

These tools span multiple systems:

• On-chain — Key NFT reads/writes plus ETH transfers via the AI signer.
• Semantic search — Pinecone-backed pinecone_search for lore, memes, and rhymes.
• Media generation & vision — OpenAI image workflows and inline renderers (e.g., generate_image_with_alt).
• Postgres/Prisma — Quota tracking, Key NFT usage, and other stateful mutations stored in our primary DB.

Server & Auth Highlights

• JWT extraction happens in dapp/app/lib/mcp/server/auth.ts, which checks headers, body payloads, and cookies. Verified claims (sub, address, tokenId) are injected into tool args under __jwt.
• Per-tool gating is opt-in. Any tool definition can set requiresJwt: true, causing the dispatcher to re-run verification and add JWT metadata to the handler args. This pattern powers the Key NFT mutation tools, crypto senders, and quota-sensitive APIs.
• Error propagation uses the ToolFailure helper in tool-errors.ts so handlers can fail('message'). The SSE pipeline picks up these errors to show red chips in the UI and feed concise summaries back to the LLM.

Tool Catalog

Each tool now has a dedicated deep dive. Use this table as a hub:

Each page covers registry wiring, handler logic, and the corresponding presenter so you can see how backend behavior maps onto the inline chips described in the Chat Experience section.

Mode Whitelists

Each chat mode (dapp/app/lib/llm/modes/configs/*.ts) declares an mcpTools array. For example:

• Rap Battle — balances aggression with limited on-chain actions (get_eth_balance, send_crypto_to_signed_in_user, mark_key_used, pinecone_search, generate_image_with_alt).
• Freestyle — unlocks more playful tools (key_nft_read, keynft_used_count, manage_key_nft, send_crypto_agent).
• Agent Battle — relies heavily on generate_rap_verse, send_crypto_to_signed_in_user, and mark_key_used to enforce the high-stakes format.