# Building on Upvera

Read this when the user wants to integrate with Upvera from their own product or tools. Full documentation lives at https://upvera.dev, and every page there also exists as Markdown at the same address with `.md` (for example https://upvera.dev/mcp.md). The index is https://upvera.dev/llms.txt.

## MCP server

- URL: `https://mcp.upvera.co/mcp` (Streamable HTTP). No API key: OAuth 2.1 with PKCE, client registration through a Client ID Metadata Document or Dynamic Client Registration.
- Scopes: `read:own` (the four read tools) and `write:drafts` (`create_draft`), requested together, plus `offline_access`.
- Limits per account: 60 reads per minute, 10 drafts per minute and 20 drafts per day.
- Setup per client: https://upvera.dev/mcp/claude-code/ · /mcp/claude/ · /mcp/cursor/ · /mcp/vscode/ · /mcp/chatgpt/
- Claude Code: `claude mcp add --transport http upvera https://mcp.upvera.co/mcp`, then `/mcp` and authenticate.
- Revoke any connection in Settings › Security › AI access on app.upvera.co.

## Sign in with Upvera (OpenID Connect)

- Issuer `https://id.upvera.co`, discovery at `/.well-known/openid-configuration`.
- Authorization code flow only, PKCE S256, `nonce` and `state` required, check `iss` in the response.
- Scopes: `openid`, `profile`, `email` (off by default, only if the person allows), `upvera:founder`.
- `sub` is pairwise: an ID made for one site. `upvera:human` carries the proof-of-personhood tier (`unsigned` < `web_key` < `device_key` < `device_attested`) and the month it was reached.
- Clients register from the startup panel after verifying their domain. Guide: https://upvera.dev/sign-in/

## Value badge

- `https://app.upvera.co/badge/{slug}.svg`, with `?lang=en|tr` and `?theme=light`.
- The slug is the one in the startup's value page, `https://app.upvera.co/value/{slug}`.
- Markdown: `[![Upvera Value](https://app.upvera.co/badge/{slug}.svg)](https://app.upvera.co/value/{slug})`

## Day roots

Every day is sealed into a root and published to https://github.com/upvera-co/ledger-roots with an OpenTimestamps proof. https://upvera.co/dogrula checks the chain in the browser.

## Rules for integrations

- Show the numbers Upvera returns. Never recompute a value or a percentage, and link back to the source page.
- Never put an API key or token in a URL, a client-side bundle or a commit.
- Drafts are the only thing an agent writes. Publishing is the person's act, in the Upvera app.