Configure Odin and HTTP clients

Connect Odin or any URL-based MCP client to Hoursmith with Streamable HTTP, a local /mcp/ URL, and an API-key header.

Some MCP clients ask for a URL instead of a command to launch. For those, run the same @hoursmith/mcp-server package in Streamable HTTP mode and point the client at the local endpoint.

Before you start

Plan: StudioAgency

You need Node.js 18+ and an hsk_ API token. In HTTP mode, the token is sent by the MCP client as a request header, not read from HOURSMITH_API_TOKEN.

Start the local endpoint

Run this in a terminal and leave it running while your HTTP MCP client is connected:

HOURSMITH_MCP_TRANSPORT=http npx -y @hoursmith/mcp-server

By default it listens at:

http://127.0.0.1:8000/mcp/

The server accepts CORS preflight requests, so browser-based MCP setup screens can test the connection.

Configure Odin

In Odin, add a new MCP server with these values:

Field	Value
Server name	`hoursmith`
Transport type	`HTTP`
URL	`http://localhost:8000/mcp/`
Authentication	`API Key (via Header)`
Custom header	`Authorization: Bearer hsk_live_...`

Replace hsk_live_... with the token you copied from Settings → API.

If your client cannot set Authorization, use one of these custom headers instead:

x-api-key: hsk_live_...
api-key: hsk_live_...
x-hoursmith-api-key: hsk_live_...

Configure another HTTP MCP client

For any URL-based MCP client, the pieces are the same:

Transport: Streamable HTTP.
URL: http://localhost:8000/mcp/ unless you changed the host, port, or path.
Authentication: send your Hoursmith token on every request using Authorization: Bearer hsk_..., x-api-key, api-key, or x-hoursmith-api-key.

Do not put the token in HOURSMITH_API_TOKEN for HTTP mode. That variable is only used by stdio clients such as Claude Desktop, Cursor, and Zed.

Optional HTTP settings

Variable	Default	Description
`HOURSMITH_MCP_HOST`	`127.0.0.1`	HTTP bind host. Use `0.0.0.0` only if you intentionally expose the endpoint beyond your machine.
`HOURSMITH_MCP_PORT`	`8000`	HTTP port.
`HOURSMITH_MCP_PATH`	`/mcp/`	HTTP endpoint path.
`HOURSMITH_MCP_HTTP_JSON_RESPONSE`	`true`	Return JSON responses for HTTP tool calls. Set to `false` only if a client specifically needs stream-style responses.
`HOURSMITH_API_URL`	`https://my.hoursmith.app`	Override the Hoursmith API host for self-hosted or staging instances.

Verify it worked

Ask the client a read-only question:

Show me my Hoursmith profile.

That runs get_me. If you see your member and workspace details, the connection is live.

If the client gets 401 unauthenticated, check that the request includes a token header and that the token starts with hsk_. The server will reject missing headers and non-Hoursmith-looking tokens before it calls the API.

Was this page helpful?