Self-Hosting Over HTTP

Self-hosting over HTTP is the right choice when you want WalletSuite MCP to run as a reusable local service instead of being launched separately by each MCP host. Use HTTP when:

your client prefers or requires a URL-based MCP server
you want one local endpoint that multiple tools can reuse
you are testing local deployment behavior or HTTP integrations
you operate production infrastructure (trading engine, vault manager, treasury ops, bot fleet) and want WalletSuite running alongside it as a long-lived local service, pinned at startup to its own OWS agent token — one deployment represents one identity

For most users, stdio is still simpler. If you do not specifically need an HTTP endpoint, use one of the Install Guides instead.

Docker image (Recommended)
Package runtime (Advanced)

These examples use the published walletsuite/mcp-server:latest image.Authentication note:

WALLETSUITE_API_KEY must be set on the HTTP server process itself
MCP clients that connect by URL do not forward that key automatically to the server

1. Create an env file

printf 'WALLETSUITE_API_KEY=your-key\nMCP_BANDS=read\nMCP_HTTP_MODE=stateless\n' > .env.walletsuite-mcp

Add OWS variables only if you need local signing or broadcast.

2. Start the server

docker run --name walletsuite-mcp --rm -d --env-file .env.walletsuite-mcp -p 3000:3000 walletsuite/mcp-server:latest

3. Verify health

curl http://localhost:3000/health

4. Connect a client

If your MCP host supports HTTP MCP servers directly, point it at:

http://localhost:3000/mcp

Generic HTTP config:

{
  "mcpServers": {
    "walletsuite": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Claude Code example:

claude mcp add --transport http walletsuite-http http://localhost:3000/mcp

Use this when you want an HTTP server without Docker but still want to install from the published package instead of from source.This path requires Node.js 22 or newer.

Start the server

MCP_TRANSPORT=http MCP_HTTP_MODE=stateless MCP_BANDS=read WALLETSUITE_API_KEY=your-key PORT=3000 npx -y @walletsuite/mcp-server

Verify health

curl http://localhost:3000/health

Connect a client

Point your MCP host at:

http://localhost:3000/mcp

HTTP modes

WalletSuite MCP supports two HTTP runtime modes:

`stateless`

This is the default and the best choice for most local HTTP setups. Use it when:

you want simpler request-per-call behavior
you do not need session-oriented behavior
you want the least operational complexity

`stateful`

Use this only when you specifically need session-oriented behavior or resumability testing. Most users do not need it for day-to-day wallet queries or transfer preparation. If you use stateful, the main tuning knobs are:

MCP_SESSION_TTL_MS
MCP_MAX_SESSIONS
MCP_SHUTDOWN_TIMEOUT_MS

Key environment variables

Variable	Default	What it does
`MCP_TRANSPORT=http`	none	Starts the server in HTTP mode
`MCP_HTTP_MODE`	`stateless`	Chooses `stateless` or `stateful`
`PORT`	`3000`	Sets the HTTP port
`MCP_BANDS`	`read`	Controls which tools are exposed
`WALLETSUITE_API_KEY`	none	Authenticates the server to WalletSuite
`MCP_SESSION_TTL_MS`	`1800000`	Stateful mode only. Session time-to-live in milliseconds
`MCP_MAX_SESSIONS`	`1000`	Stateful mode only. Maximum active sessions
`MCP_SHUTDOWN_TIMEOUT_MS`	`5000`	Graceful shutdown timeout in milliseconds

OWS with HTTP

If you want local signing on top of HTTP, add the same OWS environment variables you would use in stdio mode:

OWS_ENABLED=true
OWS_AUTH_MODE=owner or agent
OWS_PASSPHRASE or OWS_AGENT_TOKEN
chain RPC URLs if you want local broadcast

When not to use HTTP

Do not use HTTP just because it sounds more flexible. Stay with stdio if:

your host already supports local stdio servers well
you only need one host on one machine
you do not want to run or monitor a separate local service

Roadmap: hosted deployment (Q2–Q3 2026)

A hosted WalletSuite deployment is planned for consumer-scale platforms and agent SaaS — the shape where a single backend serves many end-user agents. Signing runs inside a hardware-isolated Trusted Execution Environment (TEE) with per-tenant AEAD key isolation, KMS-managed envelope encryption, and remote attestation for integrity guarantees — architecturally distinct from self-hosted OWS and not a drop-in replacement for this page’s pattern. Contact us for early-access details.

Next steps

Use OWS Local Signing if you want local signing on top of your HTTP deployment
Use Troubleshooting if the server starts but your host cannot connect

Getting Started

Concepts

Install Guides

Advanced

Self-Hosting Over HTTP

1. Create an env file

2. Start the server

3. Verify health

4. Connect a client

Start the server

Verify health

Connect a client

HTTP modes

`stateless`

`stateful`

Key environment variables

OWS with HTTP

When not to use HTTP

Roadmap: hosted deployment (Q2–Q3 2026)

Next steps

Getting Started

Concepts

Install Guides

Advanced

​1. Create an env file

​2. Start the server

​3. Verify health

​4. Connect a client

​Start the server

​Verify health

​Connect a client

​HTTP modes

​stateless

​stateful

​Key environment variables

​OWS with HTTP

​When not to use HTTP

​Roadmap: hosted deployment (Q2–Q3 2026)

​Next steps

1. Create an env file

2. Start the server

3. Verify health

4. Connect a client

Start the server

Verify health

Connect a client

HTTP modes

`stateless`

`stateful`

Key environment variables

OWS with HTTP

When not to use HTTP

Roadmap: hosted deployment (Q2–Q3 2026)

Next steps