Install
Run the Hoursmith MCP server with npx over stdio or as a local Streamable HTTP endpoint. Here are the commands and environment variables.
There's nothing to install globally. Stdio clients spawn the Hoursmith server on demand with npx;
URL-based clients can run the same package as a local Streamable HTTP endpoint.
- Plan
- StudioAgency
You need Node.js 18+ to run the server and an hsk_ API token before any
tool can call Hoursmith.
Stdio run command
Claude Desktop, Cursor, Zed, and other process-spawning MCP clients launch the server with npx,
over stdio:
npx -y @hoursmith/mcp-serverThe -y flag tells npx to download and run the package without an interactive prompt. The binary
name is hoursmith-mcp.
You don't usually run this command yourself — your MCP client does, using the config you add in the
next steps. Running it directly is mostly useful as a sanity check that Node and npx work.
HTTP run command
Odin and other URL-based MCP clients can connect over Streamable HTTP. Start the local endpoint like this:
HOURSMITH_MCP_TRANSPORT=http npx -y @hoursmith/mcp-serverThe default URL is:
http://127.0.0.1:8000/mcp/In HTTP mode, the client sends the token on each request with Authorization: Bearer hsk_...,
x-api-key, api-key, or x-hoursmith-api-key. See
Configure Odin and HTTP clients.
Environment variables
The server itself is configured through environment variables. Stdio clients usually set them in the client config; HTTP users usually set them in the terminal where the local endpoint runs.
| Variable | Required | Default | Description |
|---|---|---|---|
HOURSMITH_API_TOKEN | Yes for stdio | — | The Bearer token from Settings → API. Must start with hsk_. In HTTP mode, send the token per request using headers instead. |
HOURSMITH_API_URL | No | https://my.hoursmith.app | Override the API base URL for self-hosted or staging instances. |
HOURSMITH_MCP_CLIENT | No | hoursmith-mcp | A label identifying the calling client, sent as a User-Agent suffix. |
HOURSMITH_MCP_TRANSPORT | No | stdio | Set to http for the local Streamable HTTP endpoint. |
HOURSMITH_MCP_HOST | No | 127.0.0.1 | HTTP bind host. Use 0.0.0.0 only when you intentionally expose it beyond your machine. |
HOURSMITH_MCP_PORT | No | 8000 | HTTP port. |
HOURSMITH_MCP_PATH | No | /mcp/ | HTTP endpoint path. |
HOURSMITH_MCP_HTTP_JSON_RESPONSE | No | true | Return JSON responses for HTTP tool calls. |
Most stdio users only ever set HOURSMITH_API_TOKEN. HTTP users usually set only
HOURSMITH_MCP_TRANSPORT=http, then put the token in their client's custom headers. Leave
HOURSMITH_API_URL alone unless you're pointing at a self-hosted or staging Hoursmith.
Configure your client
Pick your tool and follow its setup guide:
Claude Desktop
macOS and Windows config file paths.
Cursor
Add the server in ~/.cursor/mcp.json.
Other clients
Zed and any stdio-capable MCP client.
Odin / HTTP clients
Use a local Streamable HTTP endpoint.