TM Finder MCP server

Stateless Streamable HTTP MCP adapter for the TM Finder Public API.

Configuration

API_KEY is the server's only environment variable. It is optional because clients can instead provide their own key in the Authorization or X-API-Key header. All non-secret server settings are defined in src/main.ts under MCP_CONFIG.

For multi-user deployments, do not set a shared API_KEY. Have each MCP client send its TM Finder API key in the Authorization: Bearer <api-key> header or the X-API-Key: <api-key> fallback header when calling /mcp. The credential is forwarded to the public API and is never included in tool arguments or results.

For a single-user deployment, set API_KEY through the shell or secret manager. The blank entries in the committed environment files are intentionally treated as unset; do not commit the real key.

Codex configuration

Codex's Bearer token env var setting expects the name of an environment variable, not the token itself. For example, start Codex from a shell where the credential is available:

export TM_FINDER_API_KEY='your-tm-finder-api-key'

Then configure the Streamable HTTP server with:

• URL: https://tm-finder-mcp.vercel.app/mcp
• Bearer token env var: TM_FINDER_API_KEY

Codex will read TM_FINDER_API_KEY and send its value as Authorization: Bearer <value>. Restart the Codex app or IDE extension after saving the MCP configuration. Do not paste the token itself into Bearer token env var; doing so makes Codex look for an environment variable whose name is the token, so no authorization header is sent.

The equivalent config.toml entry is:

[mcp_servers.tm_finder]
url = "https://tm-finder-mcp.vercel.app/mcp"
bearer_token_env_var = "TM_FINDER_API_KEY"

If Codex does not forward Authorization, use the MCP settings' static Headers section instead: X-API-Key as the key and the TM Finder API key as the value (without a Bearer prefix). The MCP server accepts this fallback and forwards the credential to the public API as a Bearer token. This stores the secret in Codex configuration, so the environment-variable method is preferred.

Endpoints

• POST /mcp — stateless MCP Streamable HTTP endpoint
• GET /health — container health/liveness endpoint

The server exposes search_trademarks. Each call costs one TM Finder API credit. An idempotency key is generated automatically; clients retrying a logical operation should pass the original idempotencyKey tool argument to avoid a second debit.

Run

# Start locally with automatic restart when source files change
npm run local

# Compile TypeScript, then run the production build
npm run build
npm start

The committed environment files contain only a blank API-key placeholder. Inject the real key through the hosting platform's secret manager; never commit it.

Terminate with SIGTERM or SIGINT for graceful shutdown. Put the service behind TLS in production and keep /mcp request bodies within the configured 256 KB limit.