> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/under-the-hood/architecture.md). # Architecture Understand the parts of Assay and how calls, signatures and money move between them. Assay connects your AI client to tools run by providers. The hosted server finds a provider and checks its result. For paid calls, a local process signs payment permission and contracts hold the money. ## How it works ```mermaid flowchart LR AI[AI client] <-->|stdio| Local[Local assay-mcp] Local <-->|MCP over HTTPS| Server[Assay MCP server] Web[Assay web app] <--> Backend[Assay backend] Server <--> Backend Server <-->|Mapped request and result| Provider[Provider endpoint and request verifier] Backend --> Checks[Result checks and settlement jobs] Local -->|Signed payment via Assay| Backend Backend <--> Contracts[Escrow, stake and config contracts] Web <-->|Wallet approval| Contracts ``` Your client connects through `assay-mcp` to `https://mcp.goassay.ai/`. The hosted MCP server exposes the tools available through that URL and your agent's access policy. It turns a tool call into a request to an eligible provider, then returns the provider's mapped result with a receipt. The web app is where you manage accounts, connections, tools and money. Its backend supplies the catalogue, access checks, routing, call records and settlement work used by the MCP server. The diagram groups these responsibilities; it does not require them to run in one process. ## The parts | Part | What it does | Trust boundary | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | | Web app | Lets you manage agents, approve spending with your wallet and configure provider listings. | A page or approval link is not itself a completed chain transaction. | | Hosted MCP server | Provides discovery, validates calls and applies URL, access and spending rules. | A cached tool name cannot bypass current access checks. | | Local `assay-mcp` | Holds sign-in tokens and a private payment key in your OS keychain. Checks payment requests, signs approved ones and forwards calls. | The payment key stays on your computer; local and wallet-approved limits both apply. | | Provider endpoint | Runs the service behind a tool. Assay maps tool arguments to its request and maps its response back. | The provider must enforce its chosen authentication. | | Provider request verifier | Checks that a signed request came from Assay, was not changed and has not already been used. Can run in middleware or a gateway. | It authenticates the incoming request. It does not judge the returned data. | | Result checks | Judge the mapped response using the tool's configured policy and record evidence for the receipt. | A returned result can still be awaiting a verdict. | | Escrow contract | Holds customer funds, enforces payment authority and caps, and holds payments before collection or refund. | Assay can submit a signature; the contract checks whether it can be redeemed. | | Stake contract | Holds provider security deposits and handles proposed penalties and disputes. | A result failure does not immediately take stake. | | Config contract | Supplies roles, verifier keys, pause state and shared limits. | These are contract settings, separate from local client settings. | Payments use **USDG** on **Robinhood Chain**. Customer escrow and provider stake serve different purposes: escrow pays for calls; stake backs the provider's quality promise. ## Example: choose your connection For paid calls, use a local client with `assay-mcp`. Hosted connectors in claude.ai and ChatGPT make free calls only because they cannot hold the local payment key. Follow [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md) for setup and [How paying works](/developers/use-tools-get-started/how-paying-works.md) for approval. For a provider, the request verifier can sit in your application or in front of it. The [authentication choices](/developers/list-your-api-get-started/api-key-or-signature.md) explain what your endpoint must enforce. ## Go further * [Security model](/developers/use-tools-advanced/security-model.md) * [Map your API to a tool contract](/developers/list-your-api-advanced/map-your-api.md) ## Next * [Life of a paid call](/developers/under-the-hood/life-of-a-call.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.goassay.ai/developers/under-the-hood/architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.