Agents: connect over MCP
Point any MCP client at mcp.encumbra.ai to read lien state and prepare transactions. The server holds no keys: your wallet signs.
When to use it
Use MCP when an assistant or agent runtime should work with liens through tool calls: check its own headroom, draft a consent, prepare a charge, or find liens to liquidate. For code you ship, @encumbra/sdk exposes the same reads and the same unsigned calls.
Endpoints
| Endpoint | Sign-in | Limit | Use it when |
|---|---|---|---|
https://mcp.encumbra.ai/mcp | None | 60 requests a minute per IP | Trying the tools, scripts, and agents that read and prepare |
https://mcp.encumbra.ai/mcp/auth | OAuth 2.1, sign in with GitHub | 120 a minute per IP, then 300 a minute per GitHub user | Steady use, a shared IP, or calls you want attributed to you |
Both serve the same tools. A token for /mcp/auth never applies to /mcp, so the URL alone picks the mode.
Connect your client
Claude Code
# Anonymous
claude mcp add --transport http encumbra https://mcp.encumbra.ai/mcp
# Signed in: add this URL instead, then run /mcp in Claude Code to sign in with GitHub
claude mcp add --transport http encumbra https://mcp.encumbra.ai/mcp/authClaude Desktop and claude.ai
Open Customize, then Connectors, choose Add custom connector, and paste https://mcp.encumbra.ai/mcp/auth. Claude reaches the server from Anthropic's cloud rather than your machine, so the signed-in endpoint gives you your own quota. On Team and Enterprise plans an owner adds the connector under Organization settings, Connectors first.
Cursor
{
"mcpServers": {
"encumbra": {
"url": "https://mcp.encumbra.ai/mcp"
}
}
}Any Streamable HTTP client
POST JSON-RPC to the endpoint with Accept: application/json, text/event-stream. The server speaks MCP revision 2026-07-28, and 2025-11-25 for clients that still open with initialize. On /mcp/auth, a request without a token gets a 401 naming the metadata your client needs to find the authorization server, register, and sign in.
curl https://mcp.encumbra.ai/health
curl https://mcp.encumbra.ai/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: tools/list" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientCapabilities":{},
"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"}}}}'Tools
Forty tools, grouped by the role that uses them. Every tool reads or prepares; none broadcasts. Calls that move tokens in, such as open, repay and addCollateral, go through @encumbra/sdk.
Reader
| Tool | Returns |
|---|---|
get_lien | Full state of a lien: parties, tokens, collateral, debt, limit, status, frozen, past due |
available | Headroom the agent can draw now; zero when the line is cut off |
is_serviceable | Whether a provider should keep serving this agent |
is_asset_enabled | Whether a financed device should run: the kill-switch it polls |
is_liquidatable | Whether a keeper can liquidate the lien right now |
health_factor | WAD-scaled health; below 1e18 is liquidatable |
collateral_value | Collateral value in debt-token units |
charge_nonce | The lien's current EIP-712 charge nonce |
past_due_since | When past-due liquidation became possible (due date plus grace window), or not past due |
claimable | Proceeds the contract holds for an account in one token: a creditor's repayments and liquidation share, or an owner's surplus |
oracle_failure | A pending oracle-failure report: when, the target oracle, and the migration window 6 to 7 hours later |
consent_nonce_used | Whether an agent's consent nonce is spent or cancelled |
next_id | The id the next lien will receive |
agent_stats | An agent's on-chain repayment record: opened, settled, defaulted, bad debt |
recommend_credit_limit | Reference underwriter: a suggested limit and LTV tier |
decode_call | Decodes EncumbraLien calldata, to check a prepared lien call before signing |
Agent
| Tool | Returns | What it is for |
|---|---|---|
prepare_open_consent | Typed data | The agent agrees to be named on a token-backed lien with exactly these terms |
prepare_open_asset_consent | Typed data | The same consent for a lease backed by one escrowed non-fungible token title |
prepare_lease_schedule_consent | Typed data | The agent agrees to the installment schedule an owner who is not the agent sets |
prepare_charge_auth | Typed data | The agent authorizes one draw of one amount, with a deadline |
prepare_cancel_consents | Unsigned call | Cancels consents the agent signed, by nonce |
prepare_freeze | Unsigned call | Freezes a lien; the owner, agent or creditor may send it |
Creditor
| Tool | Returns | What it is for |
|---|---|---|
prepare_charge | Unsigned call | Records usage on a lien under the creditor's own authority |
prepare_charge_with_auth | Unsigned call | Records usage with the agent's signed per-draw authorization |
prepare_withdraw_proceeds | Unsigned call | Withdraws what the contract holds for the caller in one token, to the caller or another address; also used by an owner for a liquidation surplus |
Owner
| Tool | Returns | What it is for |
|---|---|---|
prepare_close | Unsigned call | Closes a fully repaid lien and returns the collateral or title, to the owner or another address |
prepare_set_lease_schedule | Unsigned call | Sets an installment schedule once, with the agent's signature when the owner is not the agent |
prepare_report_oracle_failure | Unsigned call | Owner or creditor reports that the lien's oracle fails, naming the approved oracle it would move to |
prepare_migrate_oracle | Unsigned call | Owner or creditor moves the lien to the reported oracle, only 6 to 7 hours after the report |
prepare_clear_oracle_failure | Unsigned call | Anyone clears a report once the lien's oracle answers again |
Keeper
| Tool | Returns | What it is for |
|---|---|---|
list_liquidatable | Lien ids | Liens a keeper could liquidate right now |
prepare_liquidate | Unsigned call | Liquidates a defaulted lien backed by ERC-20 collateral |
prepare_liquidate_asset | Unsigned call | Repossesses a defaulted lease; the keeper pays the appraised value less its reward and takes the title |
keeper_info | Bond position | A keeper's bond, when it is active, whether it is jailed, and when it can withdraw |
check_slash | Dry run | Whether a lien's assigned keeper can be slashed now for missing its slot, and for how much |
prepare_keeper_bond | Unsigned call | Bonds the module's fixed ENC amount (approve it first) to join the keeper set |
prepare_keeper_unbond | Unsigned call | Schedules leaving the keeper set |
prepare_keeper_withdraw | Unsigned call | Takes the bond back, less any slash, after the cooldown |
prepare_slash_missed | Unsigned call | Slashes a keeper that missed its slot; anyone may send it and the sender receives the bounty |
prepare_record_excuse | Unsigned call | Records an objective reason a lien cannot be liquidated right now, which rules out the slash |
Prepare, sign, submit
- Preparea prepare tool returns an unsigned call
- Checkdecode_call reads the calldata back
- Signin your own wallet
- Submitthe contract enforces every rule
- PrepareEIP-712 typed data for the agent
- Agent signssignTypedData, no gas
- Hand overthe signature goes to the owner or creditor
- SubmitopenWithConsent, setLeaseSchedule or chargeWithAuth
What an unsigned call contains
| Field | Meaning |
|---|---|
to | The EncumbraLien contract, or the KeeperBond module for the keeper bond calls |
data | The calldata to sign. Pass a lien call to decode_call to read it back |
value | 0x0, always: liens move tokens, never native ETH |
chainId | 84532, Base Sepolia |
functionName, args | The contract function and its decoded arguments |
summary | One line saying what signing it will do |
role | Who is expected to sign it: owner, agent, creditor, keeper, or anyone |
Agent consent
An owner cannot put an agent on a lien by itself. The agent calls prepare_open_consent (or prepare_open_asset_consent for a lease), signs the typed data, and hands the signature, nonce and deadline to the owner, who submits openWithConsent with exactly those terms. The typed data carries the current governance termsHash; if governance terms change before the owner submits, the open reverts with terms mismatch and the agent signs again. A lease schedule set by an owner who is not the agent works the same way, through prepare_lease_schedule_consent and prepare_set_lease_schedule. Check a nonce with consent_nonce_used; withdraw unused consents with prepare_cancel_consents. Per-draw signatures follow the same pattern, see per-charge authorization.
Proceeds
Repayments, installments and liquidation shares are credited in the contract, not sent. A creditor reads its balance with claimable and withdraws it with prepare_withdraw_proceeds; an owner withdraws a liquidation surplus the same way.
Limits and errors
| When | Response | What to do |
|---|---|---|
| Over a rate limit | HTTP 429, Retry-After: 60, and a JSON-RPC error saying when to retry | Wait the Retry-After seconds, then retry |
/mcp/auth without a token | HTTP 401 with a WWW-Authenticate header pointing at the resource metadata | Your client starts the GitHub sign-in |
| Token without the tool scope | HTTP 403, insufficient_scope | Sign in again and approve mcp:read |
| Rate limiter unavailable | HTTP 503 and a JSON-RPC error | Retry shortly; the server refuses rather than run unmetered |
| Malformed argument | A tool result marked as an error, naming the field | Ids and amounts are decimal strings; addresses are 0x-prefixed |
| A call the contract would refuse | Prepared anyway; the transaction reverts when submitted | Read available or get_lien first |
Security model
| Property | What it means |
|---|---|
| No keys | The server holds no private key and has no signing code. It cannot move funds. |
| Unsigned output | Prepare tools return calldata or EIP-712 typed data. Nothing reaches the chain until your wallet signs and sends it. |
| Agent consent | The contract refuses a lien that names an agent unless that agent signed a consent for exactly those terms and that owner. |
| Bounded signatures | A consent opens at most one lien and expires; a lease-schedule consent covers one schedule on one lien; a charge authorization covers one amount and one nonce. Each lasts an hour by default and at most a day. |
| Rate limits | Per IP on /mcp. Per IP, then per GitHub user, on /mcp/auth. |
| Logging on /mcp/auth | One line per tool call: the tool, your GitHub id and username, success or failure, and the duration. Arguments and results are not logged. |
| GitHub sign-in | Asks for no GitHub scopes, reads your public id and username, and keeps no GitHub token. Each client gets a consent page first. |
Signing in is for attribution and quota, not a gate: any GitHub account can sign in. Access tokens last an hour and refresh tokens 30 days.