Skip to content

Document explicit MCP verification and Vault replacement #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chrisjleal merged 1 commit into from
Oct 11, 2026
Merged

Document explicit MCP verification and Vault replacement #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions mcp/secrets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Sign in first with OAuth or a server key ([Auth](./auth)). Use the signed-in pro

| Tool | Purpose |
| ---- | ------- |
| **`proofable_secret_create`** | Store a named secret as an encrypted proof |
| **`proofable_secret_create`** | Store or replace a named secret as an encrypted proof |
| **`proofable_secret_list`** | List secret metadata (alias, qHash, type). No values |
| **`proofable_secret_revoke`** | Revoke a secret proof by qHash |

Expand All @@ -30,9 +30,11 @@ When signed in, **omit `walletAddress`**. Secrets bind to your profile account f
| ----- | ----- |
| `walletAddress` | Optional when signed in; must match the authenticated profile account if set |
| `alias` | Letters, numbers, underscore; must start with a letter |
| `secretType` | `single` (default) or `bundle` (JSON object string in `content`) |
| `secretType` | `single` (default), `bundle` (key-value JSON), or `json` (one sealed JSON document) |
| `content` | Secret value stored in Vault. Encrypted at rest; never echoed back via MCP |

Saving the same alias again creates a new proof and revokes its older live proof. The result lists revoked proof IDs in `superseded`. If revocation fails after the new save, the tool reports `secret_replacement_incomplete` with both proof IDs so you can retry or revoke the older one.

## List (`proofable_secret_list`)

```json
Expand All @@ -58,7 +60,7 @@ Requires authenticated ownership of the secret proof. Omit `walletAddress` when

- Store secrets only through **`proofable_secret_create`**. Confirm the stored name and proof ID. Never print the value in chat.
- Prefer OAuth or Profile keys in MCP config only. Do not use them in app browser bundles.
- Rotate or revoke through **`proofable_secret_revoke`** and re-create if a value is exposed.
- Rotate by saving the same alias again, or revoke through **`proofable_secret_revoke`** if a value is exposed.

<CardGroup cols={2}>
<Card title="Auth" icon="lock" href="./auth">
Expand Down
8 changes: 5 additions & 3 deletions mcp/tools.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,15 @@ Call **`proofable_context`** once, then pick the tool for the job.
| List what you can verify | `proofable_verifiers_catalog` | Required inputs and supported networks. |
| Reuse a proof | `proofable_proofs_check` | Read-only. Reports whether a current proof already satisfies the request. |
| Finish what's missing | `proofable_verify_or_guide` | Reuses a proof, or returns the next step. |
| Create or refresh a proof | `proofable_verify` | Creates the proof when a new one is needed. |
| Create a proof in-session | `proofable_verify` | Creates the proof when the signed-in account can authorize it. |
| Prepare an outside signature | `proofable_verify_prepare` | Returns the exact signing string and timestamp; creates no proof. |
| Submit an outside signature | `proofable_verify_submit` | Creates the proof from a signed prepared check. |
| Read a proof | `proofable_proofs_get` | Current proof records and status. |
| Update or review a proof | `proofable_proofs_update` | Change title/tags, vote, or comment on the same proof. |
| Create or import an agent | `proofable_agent_create` | Links the agent to your profile. Optional separate spend account and controls. Pass an existing account address for dedicated spend. |
| Confirm the agent is ready | `proofable_agent_link` | Identity and the permissions that account needs. |
| Load the agent | `proofable_agent_mount` | Identity, permissions, skills, and current settings. |
| Store a secret | `proofable_secret_create` | Encrypted Vault secret. |
| Store or replace a secret | `proofable_secret_create` | Encrypted Vault secret; the same alias replaces its prior value. |
| List secrets | `proofable_secret_list` | Stored names and details. Never the secret itself. |
| Revoke a secret | `proofable_secret_revoke` | Removes a stored secret by proof ID. |

Expand All @@ -44,7 +46,7 @@ Pro adds only the four tools needed to run and manage jobs. Product connections,
| Tool | Address field | Verifiers / filters |
|------|---------------|---------------------|
| `proofable_proofs_check` | `wallet` | `verifiers` |
| `proofable_verify`, `proofable_verify_or_guide` | `walletAddress` | `verifierIds` |
| `proofable_verify`, `proofable_verify_prepare`, `proofable_verify_submit`, `proofable_verify_or_guide` | `walletAddress` | `verifierIds` |
| `proofable_proofs_get` | `identifier` | optional `tags` (comma-separated proof tags) |
| `proofable_proofs_update` | `qHash` (proof ID) | optional metadata, `vote`, or `comment` |

Expand Down
11 changes: 6 additions & 5 deletions mcp/verify.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@ icon: circle-check

Use **[`proofable_verify_or_guide`](./verify-or-guide)** as the normal trust path. It reuses a qualifying proof when one exists or returns the one next step needed to finish verification.

Use **`proofable_verify`** when the signed-in account can complete a known check in-session and a new proof is actually needed. Ownership checks finish here. Share a hosted link only when this tool returns one.
Use **`proofable_verify`** when the signed-in account can complete a known check in-session and a new proof is actually needed. Ownership checks finish here.

When a separate signer is required, call **`proofable_verify_prepare`** to get the exact signing string, then **`proofable_verify_submit`** with its signature and original timestamp. Preparation does not create a proof.

Use **`proofable_proofs_check`** only when the user explicitly needs a yes/no eligibility, gate, or access answer.

Expand All @@ -22,17 +24,16 @@ When signed in, **omit `walletAddress`**. The tool uses your profile account fro
| `walletAddress` | No | Omit when signed in; required only when acting for another account |
| `data` | No | Check inputs (see each [check](../verification/verifiers)) |
| `chain` | No | CAIP-2 chain when needed |
| `signature` | No | Provided in the finalize step |
| `signedTimestamp` | No | Provided in the finalize step |
| `signedTimestamp` | No | Optional timestamp for direct creation or preparation |
| `options.returnUrl` | No | Where to send the user if a hosted step is needed |
| `options.publishToHub` | No | Record the proof on the hub chain. Offchain by default. Does not change who can see the proof. |

```json
{ "verifierIds": ["ownership-basic"], "data": { "content": "Hello Proofable" } }
```

Signed-in sessions do not send `signature` or `signedTimestamp`. Those fields exist only when the session cannot authorize the account.
The direct tool does not ask for a signature. For a separate signer, pass the `walletAddress`, `verifierIds`, `data`, and `chain` used in preparation to `proofable_verify_submit`, together with the returned `signedTimestamp` and the signature over `signerString`.

@chatgpt-codex-connector chatgpt-codex-connector Bot Oct 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Carry publish options into the submit call

For the separate-signer flow, this list omits the options object documented immediately above. A caller that prepares with options.publishToHub: true and then follows this instruction will submit without that option; the verification API defaults a missing publishToHub to false (openapi/public-api.json:247-253), so the proof is created offchain instead of being published. Instruct callers to pass the original options—or, more generally, every prepared request field—unchanged to proofable_verify_submit.

Useful? React with 👍 / 👎.


## Output

A plain-language **Passed**, **Action needed**, or **Blocked** result. On success, the tool also returns the proof ID in `qHash` for your server. A hosted link appears only when the check needs an outside step.
A plain-language **Passed**, **Action needed**, or **Blocked** result. On success, the tool also returns the proof ID in `qHash` for your server. `proofable_verify_prepare` returns signing details or a hosted fallback for an outside step.
Loading