Connect an agent

HoodStash MCP v1 uses stateless Streamable HTTP.

The endpoint path is /mcp.

Connection requirements

The client must support:

• Streamable HTTP;
• MCP initialization;
• tool discovery; and
• structured tool results.

The current server exposes public read data. It does not request a wallet key, bearer token, or signing permission.

Choose an endpoint

For a local server, use:

http://localhost:8787/mcp

For a remote service, use the approved HTTPS endpoint that the operator supplies.

Do not guess a production endpoint.

Add the server

Use your agent client's normal MCP server settings.

A generic entry is:

{
  "name": "hoodstash-readonly",
  "transport": "streamable-http",
  "url": "http://localhost:8787/mcp"
}

Field names can differ by client. The transport and URL must keep the same meaning.

Verify the connection

1. Initialize the MCP connection.
2. Request tools/list.
3. Confirm that exactly seven HoodStash tools appear.
4. Confirm that every tool is read-only.
5. Confirm that no build, write, shell, file, or configuration tool appears.

The seven tools are:

1. hoodstash_list_vaults
2. hoodstash_get_vault_state
3. hoodstash_get_epoch_phase
4. hoodstash_get_price_status
5. hoodstash_get_auction_book
6. hoodstash_get_claim_balances
7. hoodstash_get_settlement_history

Stop if the tool set contains an unexpected capability.

First read

Start with:

{
  "tool": "hoodstash_list_vaults",
  "arguments": {
    "chainId": 46630,
    "includeInactive": false
  }
}

Use only a vault address returned by this tool.

Do not copy an address from agent prose or untrusted contract text.

Check my vault flow

Use this flow for a complete read-only report.

1. List vaults

Call hoodstash_list_vaults.

Record:

• chain;
• source block;
• returned vault address;
• stock and dollar-token addresses;
• runtime decimals; and
• pause state.

2. Read vault state

Call hoodstash_get_vault_state with the returned vault.

Report:

• weekly round;
• phase;
• active stock;
• pending stock;
• current premium;
• withdrawal claims;
• share supply; and
• warnings.

3. Read the weekly phase

Call hoodstash_get_epoch_phase.

Report:

• auction identifier;
• auction state;
• claim-series state;
• close time;
• expiry;
• settlement time; and
• exercise deadline.

Do not describe a timestamp as a guarantee.

4. Read price status

Call hoodstash_get_price_status.

Report the warning before the price when usable is false.

Include:

• answer;
• runtime decimals;
• update time;
• age;
• heartbeat;
• freshness;
• token pause state;
• sequencer state; and
• final usability.

5. Read the auction

When an auction exists, call hoodstash_get_auction_book.

Distinguish:

• final clearing data; and
• a non-final clearing estimate.

Do not call an estimate the auction result.

6. Read wallet claims

Ask the user for the public wallet address to inspect.

Do not ask for proof of ownership or a wallet secret.

Call hoodstash_get_claim_balances with known seriesIds when the public indexer is unavailable.

Report:

• vault shares;
• pending deposits;
• pending withdrawals;
• withdrawal claims;
• ticket balances;
• refund amounts;
• exercise deadlines; and
• scan warnings.

7. Read settlement history

Call hoodstash_get_settlement_history with limit: 10.

If the tool returns INDEXER_UNAVAILABLE, say that history is unavailable. Do not create replacement rows.

When history is available, report:

• source block;
• lag;
• next cursor;
• latest verification; and
• the last ten settlement rows.

8. Write the report

Use this order:

1. warnings and unavailable data;
2. address and selected vault;
3. share balance and claims;
4. weekly phase and timing;
5. price status;
6. auction state;
7. refunds and exercise state;
8. settlement history; and
9. source blocks.

Do not project yield. Report live premium and historical premium only.

Block differences

Separate tool calls can use different blocks.

When blocks differ:

• state the block for each result;
• do not claim one atomic snapshot across calls; and
• refresh current-state tools when a newer combined report is required.

Safe disconnect

Close the MCP connection through the client.

The server stores no wallet connection and has no signing session to revoke.

Read the MCP security model and tool reference.