# 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:

```sh
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:

```toml
[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

```sh
# 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.