Self-Hosting Over HTTP

This page is about transport, not signing. “Self-hosting over HTTP” means running the MCP server itself as an HTTP service. It is independent of signing: you can run the MCP server over HTTP and signing still runs through MPC. See Choose Your Setup for the transport decision guide.

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, treasury ops, bot fleet) and want WalletSuite running alongside it as a long-lived local service

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

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

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

Signing over HTTP

This page is about transport: it controls where the MCP server runs, not where signing happens. You can run the MCP server over HTTP and signing still runs through MPC 2-of-2. See Choose Your Setup.

Next steps

Use Security Model to understand how signing works with your HTTP deployment
Use Troubleshooting if the server starts but your host cannot connect

​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

​When not to use HTTP

​Signing over HTTP

​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

When not to use HTTP

Signing over HTTP

Next steps