timon-mcp
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
timon-mcp
Timon plugin (behavior, API 15) that exposes a stateless Streamable HTTP MCP server. An MCP client mandates the pilot. The MCP mandates, the pilot orchestrates: the plugin forwards the mandate and reports the reply. It does not change agents, MCP servers, skills, secrets, or administration.
POST /mcp requires a bearer token. Without the URL settings, the OAuth routes answer that the plugin is not configured.
Licensed under the GNU Affero General Public License v3.0 only. See LICENSE.
Install
Node.js >=22.13 <23 || >=23.4. From this directory, or from a packed archive:
timon plugin add .timon plugin add accepts a folder, a .tgz, or a .zip.
The package is not signed. Timon loads an unsigned plugin only on a licensed installation with developer mode open. In timon.config.json:
{
"developer": {
"unsignedPlugins": true
}
}Without that flag the package can be installed and is not loaded. Developer mode does not bypass the licence.
Until the plugin is signed, missions:spawn stays refused until the id is approved. Tasks created from the background identity go through the same policy and the same quota. In timon.config.json:
{
"pluginPolicy": {
"spawn": {
"approved": ["timon-mcp"],
"max": 5,
"windowMs": 3600000
}
}
}max and windowMs are the operator's quota (here, 5 starts per hour, as in the Timon documentation example). A signed plugin is approved by its signature and stays subject to the quota.
Related MCP server: nitro-mcp-server
Endpoint
POST /api/plugins/timon-mcp/mcp
JSON-RPC 2.0, one request per call, response application/json. No SSE stream, no session. Mcp-Session-Id is optional and ignored. The spoken revisions are 2025-06-18 and 2025-03-26. An unknown params.protocolVersion at initialization receives the latest. On initialize, MCP-Protocol-Version is not checked. After initialize, including on notifications, a present and unknown MCP-Protocol-Version answers 400. An absent header is accepted.
GET /mcp and DELETE /mcp answer 405 when the handler is reached. On the daemon those methods are not public paths: an anonymous client receives 401 before the handler.
The manifest declares seven public paths (http:public), at most ten. The daemon limits each one: 60 requests a minute per address, a 64 KiB body, and a cross-site POST is refused. An Origin from another host is refused (403) after authentication. When Host carries a port, the Origin port (written or implicit) must be the same. When Host carries none, an Origin of the same host with no port is accepted over http and over https: behind TLS the daemon often sees Host: example.com and Origin: https://example.com. A non-browser client, with no Origin, is accepted. A JSON-RPC batch (an array) is refused.
GET /health answers { "ok": true, "id": "timon-mcp" }. This route is not public: it follows the daemon session.
Authentication
The plugin is both the protected resource and the authorization server (MCP authorization, revision 2025-06-18). Paths have no dot: a segment of routes.publicPaths cannot contain one. The /.well-known/… URLs are rewrites of the reverse proxy, below. The plugin does not serve them.
Method | Path | Role |
|
| Protected-resource metadata (RFC 9728). |
|
| Authorization-server metadata (RFC 8414). PKCE |
|
| Dynamic client registration (RFC 7591). Public clients only. No |
|
| Consent page, self-contained HTML, server-side CSRF token. |
|
| Decision. An approval issues a single-use code, at most 60 seconds. |
|
| Code exchange (PKCE S256) or refresh-token rotation (RFC 6749, form body or JSON). |
|
| MCP endpoint. |
OAuth 2.1 here is dynamic client registration plus PKCE S256. code_challenge_method=plain is refused.
While public_url, issuer, or resource is missing or is not an absolute http/https URL, with no userinfo, query, or fragment, these routes answer 503 with error: not_configured. The authorization page is then HTML that issues no code. No host is hard-coded.
resource (RFC 8707) is required at authorization and at the exchange. It must be exactly the configured address. A token issued for another address is refused at the MCP endpoint.
Without an Authorization header, POST /mcp answers 401:
WWW-Authenticate: Bearer resource_metadata="https://mcp.example/.well-known/oauth-protected-resource"A token that is present but unusable, unknown, expired, or for another audience adds , error="invalid_token". The JSON body stays { "error": "unauthorized", "message": "…" }. The token is not in it. A token in the query string is ignored. The Bearer scheme is case-insensitive. Past 512 characters, the presented value is refused.
The access token is opaque and lasts 15 minutes. The refresh token lasts 30 days, rotates on every use, and can be revoked. Presenting a refresh token that has already rotated revokes its whole family, including the token that replaced it and the access tokens of that family that are still in flight. Until that reuse, the previous access token stays valid until it expires. The authorization code is removed on first presentation, even when the PKCE verifier is wrong.
redirect_uri must be https, or http limited to localhost and 127.0.0.1 (local CLIs). http://localhost.evil.com is refused. The URI is bound to the registered client, by exact comparison of the registered string. Dynamic clients are capped at 128. When that cap is reached, the same transaction removes clients created more than 24 hours ago that hold no live row: no unrevoked token still before expires_at, no code, no consent request. The count is taken again afterwards. Registration answers 403 only when the cap still holds.
The same removal can be run by hand on the plugin database. cutoff is the current time minus 24 hours, now_ms is the current time, both in Unix milliseconds:
DELETE FROM oauth_clients
WHERE created_at < :cutoff
AND client_id NOT IN (
SELECT client_id FROM oauth_tokens
WHERE revoked_at IS NULL AND expires_at > :now_ms
)
AND client_id NOT IN (SELECT client_id FROM oauth_codes)
AND client_id NOT IN (SELECT client_id FROM oauth_requests);Codes, tokens, and the CSRF secret are stored only as SHA-256 digests. The subject is the digest of the address, not the address. Expired rows are purged. None of this is written to the logs. The plugin logs only fixed phrases (oauth: client registered, oauth: code issued, oauth: tokens issued, oauth: refresh rotated, oauth: authorization refused). An unexpected failure is logged as oauth: request failed (<name>), where <name> is error.name (for example TypeError). The error message is not logged.
Settings
Permission settings. Values are read on every request. Empty at the start, except the documentary right.
Key | Role |
| Public origin of the plugin, without a trailing slash. Used for the |
| OAuth issuer, without a trailing slash. The plugin is the authorization server. Often the same origin. |
| Canonical address of the MCP endpoint, the value of the |
| Header read only on |
| Name of the right expected on the surface. Default |
| Allowed addresses, separated by commas, spaces, or semicolons. Empty: refuse everyone. |
Vault secret
One secret, read only: TIMON_MCP_BEARER_TOKEN. It is the static token for CLIs on the host. Create it in the vault, then:
timon secret grant TIMON_MCP_BEARER_TOKEN --scope agent:plugin:timon-mcpWithout a grant, ctx.secrets.get returns empty: the static token is disabled, and the plugin does not crash. The value is read again on every call. The comparison is of SHA-256 digests, in constant time. The name is the constant shared with the manifest, never a literal in the call.
This token is not bound to an audience. It does not replace OAuth for clients that discover the server from the 401 challenge.
Identity
Put /oauth/authorize behind an authentication proxy (a session cookie, a magic link, or any equivalent). The proxy serves its own login page, then sends the browser back to the requested path, including /oauth/authorize. It applies the right before it proxies: only addresses of accounts that hold the right on the surface get through.
It forwards one header upstream. The default name is x-forwarded-email, the convention used by authentication proxies such as oauth2-proxy. Set identity_header when the proxy uses another name.
There is no header for a right, a level, or an internal or external marker. The plugin assumes none. expected_right is only a label.
IdentityResolver (lib/auth/identity.js) returns { subject, email } or null. The header name comes from the setting when that value is non-empty, otherwise from the shipped default x-forwarded-email, including when the saved value is blank. It refuses a missing or empty header, and an address that is not on the allowlist. An empty allowlist refuses everyone. The refusal is an HTML page, with no redirect and no code. The address is not shown.
The header is read only on GET and POST /oauth/authorize. On /mcp and on the other routes it is ignored: it does not stand in for a token.
The subject stored with the code and the tokens is the SHA-256 digest of the normalized address (trimmed, lower case). The logs do not contain the address in clear text.
Threat model
A client on the outside cannot forge the header. The edge strips it on the public paths, then the authentication proxy sets it after checking the session. The strip line targets x-forwarded-email, or the name saved in identity_header when that setting is non-empty.
Any local process that can reach the daemon can set this header itself. That is an accepted limit on the host: the daemon is not exposed directly.
The allowlist is defense in depth. The proxy has already filtered the right. An empty list grants nothing, even if a header arrives.
What the reverse proxy must pass through
A reverse proxy often strips Authorization and Cookie on public paths.
That fits /oauth/token, /oauth/register, and the metadata documents. Consent does not use a cookie: the CSRF token is in the form and its digest is in the database. /mcp needs Authorization to reach the plugin, so that path must be public with the header forwarded. That change is on the proxy, not in this repository.
Reverse proxy
Any TLS reverse proxy rewrites the public URLs onto the plugin prefix. /.well-known/* is not a plugin route: the proxy rewrites it. Fictitious host, nothing is installed by this repository:
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
rewrite ^/.well-known/oauth-protected-resource$ /api/plugins/timon-mcp/oauth/protected-resource last;
rewrite ^/.well-known/oauth-authorization-server$ /api/plugins/timon-mcp/oauth/authorization-server last;
rewrite ^/oauth/(.*)$ /api/plugins/timon-mcp/oauth/$1 last;
rewrite ^/mcp$ /api/plugins/timon-mcp/mcp last;The daemon compares Origin with Host. proxy_set_header Host $host; forwards the public host the client saw. Without that line the daemon would see the upstream address and refuse an Origin of the same site. proxy_set_header X-Real-IP $remote_addr; replaces any client-supplied value with the address the proxy actually saw. /mcp must forward Authorization through to the daemon. Public paths clear the identity header at the edge, before the authentication proxy sets it, as above. proxy_pass to the daemon is an operator setting, not a value of the plugin.
Clients
OAuth clients start from the 401 and from resource_metadata, register a public client, then run the authorization-code flow with PKCE S256. The operator fills in the three URLs and the allowlist, and places the authentication proxy in front of /oauth/authorize. No token value belongs in the repository.
CLIs on the host use the static token. Same shape, fictitious URL:
{
"mcpServers": {
"timon": {
"type": "http",
"url": "https://mcp.example/mcp",
"headers": {
"Authorization": "Bearer <TIMON_MCP_BEARER_TOKEN>"
}
}
}
}<TIMON_MCP_BEARER_TOKEN> names the vault secret. It is not a value to paste.
Tools
The list is closed. Another name returns an isError result, unknown tool, with no facade call. Every schema has additionalProperties: false.
Tool | Role |
| Mandate to the pilot. Without |
| Mission state and the agent's last message, through |
| Same shape as |
| Missions of the plugin: |
| Tasks visible to the plugin, through |
| A |
spawn sends no override (model, backend, extraSkills, extraMcp, allow).
get_reply does not declare missions:transcript. The body of the last message is returned only when the mission already carries it (last_message or messages). Otherwise the reply contains the summary and the state, and message is null.
wait uses ctx.events.on('turn_complete') when that call is available. The permission events:subscribe is not declared: if the call throws, the plugin polls the state at a short interval. done becomes true on turn_complete for this mission, or when the status is terminal (completed, failed, terminated, cancelled). A conversation that is still open stays running: polling the status alone can time out with done: false.
A policy refusal (PluginPolicyError, or reason: 'spawn_policy') is a tool result with isError, and the text waiting for the operator's approval. It is not an HTTP 500, and the plugin does not retry the call.
Call identity
A public route has an anonymous caller. In that context, missions.send is forbidden and missions.list / get read every mission. Each tool therefore runs outside the request, under the background task identity plugin:timon-mcp, through the pump started in apply() (lib/mcp/job-runner.js). The plugin then sees only the missions it started and the tasks it created.
Permissions
http:public, missions:spawn, missions:read, missions:control, kanban:read, kanban:write, settings, secrets:read, storage:sql.
missions:control is for send. The tools expose neither kill, nor fork, nor stopScope. secrets:read is only for the static token. storage:sql is for OAuth clients, codes, and tokens. The standalone host uses the same database for host_pending_cards and host_decisions. No configuration right (agents:*, mcp-servers:*, skills:*, secrets:manage, secrets:list, secrets:broker, admin, agents:privileged-config).
Standalone mode
This mode runs the same plugin without loading it into the daemon. It is provisional. While a release refuses an unsigned plugin, a small host can serve the routes itself. When a later release loads the plugin, point the reverse proxy back at the daemon. One proxy_pass line switches to the host, and the same line pointed at the daemon restores the plugin. The paths stay /api/plugins/timon-mcp/….
The host listens on the loopback interface only. TIMON_MCP_PORT chooses the port. When it is unset, the port is 3098. It needs Node.js >=22.13 <23 || >=23.4, because node:sqlite is a stable built-in on that range, and has no npm dependency. The process checks the version before it loads that module: an older Node exits with a message on stderr and a non-zero status. The daemon 0.1.7 ships Node 22.23.4, so installing the plugin into the daemon is unchanged. lib/ is unchanged: the host builds the plugin context and calls apply().
The host calls the local daemon over HTTP. TIMON_DAEMON_URL must stay on the loopback. The daemon token is read from a file on every call (TIMON_DAEMON_TOKEN_FILE, default ~/.timon/daemon-token) and is never written to a log. The static bearer is the environment variable TIMON_MCP_BEARER_TOKEN. Settings are a JSON file (TIMON_MCP_SETTINGS) using the same keys as the manifest. State is a sqlite file (TIMON_MCP_DB, default ~/.timon-mcp/state.db) and uses the plugin migrations.
Thirty daemon calls are possible. Five of them serve the plugin tools: create a mission, read one mission the host created, send a message to that mission, create a chore task, and read one task. Six more serve the mission tools below: list every mission, read one message, steer a turn, interrupt a mission, stop one mission, and stop an agent or a project. Two more serve the kanban tools: list every task, and change one task (PUT /api/tasks/:id). There is no DELETE /api/tasks/:id. Four more serve the project and agent tools: list projects (GET /api/projects), list agents (GET /api/agents), read one agent (GET /api/agents/:name), and send a direct message (POST /api/messages). None of those four accepts a query. Ten more serve pipelines, workflows, and routines: GET /api/pipelines, GET /api/pipelines/:id, GET /api/pipelines/runs/:runId, POST /api/pipelines/:id/run, GET /api/workflows, GET /api/workflows/:id, GET /api/workflows/:id/runs, POST /api/workflows/:id/run, GET /api/routines, and GET /api/routines/:id. None of those ten accepts a query. One more is the read-only GET /api/permissions. It takes no query, including no mission_id. Two more serve a decision. POST /api/permissions/:id/resolve sends only the bodies under Answering a waiting card. The id is a lowercase UUID and the path takes no query. GET /api/auth/me is read only to copy user.id into the journal. The rest of that payload, including any address, is not logged, not stored, and not returned. No other route under /api/auth or /api/permissions is called. The host pattern for those ids is :auto, so a workflow slug may contain a dot. runs, node-types, import, and hooks are not workflow ids: they are their own daemon routes and are refused. Any other method, path, query key, or body field is refused before the network. A query string stuck on the path is refused, including an allowlisted key. Query keys are accepted only as each list's allowlist. The mission list accepts project, agent, status (running, completed, failed, terminated), and limit. The task list accepts status only (PENDING, IN_PROGRESS, DONE, BLOCKED). Release 0.1.8 has no limit, project, agent, type, or pagination on GET /api/tasks. full would return the uncut texts and is refused. done_limit only windows DONE rows and still returns every other status, so it is not a bound and is not sent. project, agent, and type are applied by the host on the rows that came back. This one response may be read up to 8 MiB. Past that, list_all_tasks returns too_large and names status and get_task. It does not report the daemon as unreachable. Each pipeline, workflow, and routine read uses the same 8 MiB ceiling, including a single get: a workflow row carries its draft. Past that, the tool returns too_large and names the route template. It does not report the daemon as unreachable. Every other daemon response stays capped at 1 MiB. GET /api/permissions uses that cap. Past it, list_pending returns too_large and does not report the daemon as unreachable. The host sends no query on that route, so it cannot shrink the body. %2f and .. are refused, and so are the daemon's own words latest, search, and delegate used as a mission id. active, spawn, ephemeral, and main are not agent names on a path: they are their own daemon routes and are refused. A read accepts a display name ([A-Za-z0-9._-]{1,255}, including an ephemeral _eph-…). 255 is one directory, the daemon's hard bound on a stored name. That name may be a list filter, the agent of stop_scope, or GET /api/agents/:name. ., .., and those four route words are still refused before the call. A launch, a task assignment, and a direct message stay _main or <project>.<role>. 97 is the longest name release 0.1.8 fabricates (<slug>.<role>, a project slug of 1..64 and a role id of 2..32). That length is a read, not a launch. The host still records the missions and tasks it created. The plugin tools list_missions, get_reply, ask_main, list_tasks, and create_task read and write only those recorded ids. A list of recorded ids reads at most the 50 newest. The same call stops after 60 seconds, checked before each of those reads, and fails with a timeout instead of returning the rows already gathered. One read already started can still finish inside its own 20 second cap, so the list stays inside the idle limit below. An id the daemon answers with 404 is dropped from that record. list_all_tasks is one daemon read of GET /api/tasks, not that per-id walk.
A launch names an agent that already exists: _main, or <project>.<role>, where both parts match ^[a-z0-9][a-z0-9-]{0,39}$, so the name is at most 81 characters. The host does not create the agent. Overrides (model, backend, extraSkills, extraMcp, allow, permissionMode) are refused before the network.
spawn, send, steer, stopping one mission, stopping an agent or a project, task creation, a direct message of kind request, running a pipeline, and running a workflow share one sliding window. TIMON_MCP_SPAWN_MAX is how many of those calls are allowed (default 5). TIMON_MCP_SPAWN_WINDOW_MS is the window in milliseconds (default 3600000). Past the ceiling the tool result is isError, with the text waiting for the operator's approval, and the daemon is not called. Listing missions, reading a mission, reading one message, and interrupting a turn do not take a slot. Listing tasks, reading a task, updating it, and moving it do not take a slot either. Listing projects, listing agents, reading one agent, and a direct message of kind msg do not take a slot. Listing and reading pipelines, workflows, routines, and workflow runs do not take a slot. Listing pending cards does not take a slot. Answering a question, resolving an approval, and reading the decision journal do not take a slot. A run whose input is refused does not take a slot. A run the daemon answers with an error still does: the slot is taken before the call. The daemon token is a super-administrator, so this ceiling is the host's own quota.
The mission tools, the kanban tools, the project and agent tools, and the pipeline, workflow, and routine tools are mounted by the host on POST /mcp, in front of the plugin's six tools. They need the same plugin bearer. They are absent when the plugin runs inside the daemon. lib/ and the manifest are unchanged. The host does not call ctx.agents, so projects:read, agents:read, and messages:send are not declared. It does not call ctx.pipelines, ctx.workflows, or ctx.routines, so pipelines:read, pipelines:run, workflows:read, workflows:run, and routines:read are not declared. It does not call ctx.questions or ctx.events.on, so questions:read, questions:answer, and events:subscribe are not declared. A run sends exactly { input }. input is a JSON object of at most 64 KiB. draft, backend, model, permission, and overrides are refused, including as keys of input. draft would run the unpublished graph, so it is never sent. The projections drop prompts, drafts, run context, triggers, owners, and override fields. A pipeline keeps the {{input.name}} keys, so a run still knows what to pass. A workflow get keeps the node id and type only. The list and the detail are projections: the prompt, the transcript, the overrides, the owner, and the working directory are not returned. The message tool reads one event (GET /api/missions/:id/messages/:eventId) and returns at most 20,000 characters of its text. A task projection drops the same kind of field: overrides, attachments, and the worktree path. Description and comment are cut at 20,000 characters. A project row is slug, name, and status. An agent list row is name, role, project, and orchestrator. A detail adds reports_to and ephemeral. The system prompt, privileged config, MCP servers, secrets, skills, and absolute paths are not returned. POST /api/messages is the only write of this group. from_mission and from_agent are fixed by the host (00000000-0000-4000-8000-0000000000aa and plugin:timon-mcp). The caller cannot set them. The body is at most 20,000 characters. kind is msg or request. A work-return payload is refused before the network. No route writes an agent, a file, a skill, an MCP server, or a project.
Tool | Role |
| Every mission. Optional |
| State of one mission. No prompt. |
| One message of that mission, by |
| Follow-up on any mission. Counts against the window. |
| Redirects the turn in progress. Counts against the window. |
| Interrupts the turn. Does not count against the window. |
| Stops one mission. Counts against the window. |
| Stops one |
| Starts |
| Every task. Optional |
| One task, including description, base, blocked reason, and done comment. |
| Creates |
| Title, description, priority, dependencies, or agent. At least one. |
| Status. |
| Projects: |
| Agents, including an ephemeral |
| One agent by a path-safe display name, including |
| Direct message to an existing agent. |
| Pipelines: id, name, description, |
| One pipeline. Same projection as the list. |
| Runs a pipeline. |
| One pipeline run and its steps (task, agent, type, status). The run input and the step prompts are not returned. |
| Workflows: id, slug, name, description, project, enabled, published version, agent, and the last run's id and status. No draft, no owner. Optional |
| One workflow by id or slug. Adds the node id and type. No node config, prompt, or script. |
| Runs of one workflow: id, version, status, start, end, and error. No context, input, trigger, or owner. |
| Runs the published version. |
| Routines: id, name, agent, task type, cron, enabled, project, and the run times. No prompt, no owner. Does not enable or disable. Optional |
| One routine. Same projection as the list. |
| Questions, kanban plans, and tool approvals still waiting. An approval adds |
| Answers a waiting question or kanban plan. |
|
|
| The decision journal, newest first. Optional |
PUT /api/tasks/:id is the only task write besides creation. The body is a whitelist: title, description, agent_name, priority, deps, status, blocked_reason, done_comment. Release 0.1.8 stores done_comment only when that same request changes the status, so a comment is a field of move_task and not its own tool. A comment sent alone is not a call. Creation adds type, project, and optional base. Backend, model, permission, skills, MCP servers, tools, fallback, and any other field are refused before the network. create_task stays a chore for <project>.main.
In this mode summary is null. The mission route used here does not carry one.
Public paths keep the daemon limits: 60 requests a minute per address, a body of at most 64 KiB, and a cross-site POST is refused. The address is the socket peer. X-Real-IP is used only when TIMON_MCP_TRUST_PROXY=1 and that peer is loopback, which is how the reverse proxy on this machine reaches the host. The proxy must set proxy_set_header X-Real-IP $remote_addr;. Any other value of the setting, or a peer that is not loopback, ignores the header. X-Forwarded-For is ignored. GET /health is not a public path.
Any response sent before that body has been read leaves through one exit: Connection: close, then at most 1 MiB of the unread body is discarded over at most 5 seconds, then the socket is destroyed. That covers a non-public path, an unknown prefix, a method this host does not serve, a cross-site POST, a body past 64 KiB, a rate limit, and any later status written while the body is still unread. The server also stops incomplete headers after 10 seconds and an unfinished request after 30 seconds. An idle socket is closed after 120 seconds. wait writes nothing for up to 50 seconds. That handler can also make three daemon reads: one before the countdown starts, one poll still in flight when the countdown ends, and one final read. Each read is capped at 20 seconds. Ten seconds of margin keep the last read from losing the socket. Incomplete requests are checked every second, so those deadlines fire on time.
Pending cards are read from GET /api/permissions and projected before they leave the host. A question (ask_user whose payload validates) keeps the whitelist of the question facade: type question, id, mission_id, agent, created_at, expires_at, questions (question, header, options of label, description, and actor when it is agent or user, multi_select, placeholder), and plan set to null. A kanban plan is type series_plan, with questions empty and plan holding title (the chantier) and volets (title, description, group). Anything else, including an ask_user payload that does not validate, is type approval with tool_name (or the literal tool when the name is not safe) and command. This is a webhook contract change: an approval's webhook now carries command, the same value as list_pending. command is the tool input's command when that value is a non-empty string. Otherwise, when tool_name is one backtick segment that covers the whole string, command is the text inside the backticks and tool_name is the literal shell. The backticks are not trimmed: a surrounding space, two segments, or a partial wrap stays tool and does not supply command. A non-empty input.command keeps priority and the tool name stays the safe name or tool. The preview is cut to 160 characters. A bearer token and a hex run of 32 or more characters are replaced by [redacted]. A dashed UUID is not such a run, because the dashes split it. command is null when neither source is present. The webhook projection of an approval is type, id, mission_id, agent, created_at, expires_at, tool_name, and command. It has no entry, no input, no shell_command, and no script_previews. Every other input field is omitted. shell_command, script_previews, tool_use_id, scopes, choices, and onPaste are never copied, on either path. A question or a kanban plan keeps its whitelist on both paths and does not carry command. expires_at is created_at + timeout_ms when timeout_ms is a positive safe integer, otherwise null. A card whose id is not a lowercase UUID, whose mission id is not one this host already accepts, whose agent is not a displayable daemon name ([A-Za-z0-9._-]{1,255}, one directory, including an ephemeral _eph-… id; . and .. are dropped), or whose created_at is not a non-negative safe integer is not projected. The host logs pending card dropped id=<id> when that id is a string, and pending card dropped otherwise. The line carries the id alone and does not include the card. While that id is still in the daemon list, the host treats the raw id as seen and does not emit resolved. resolved is emitted only when the id is absent from a complete list. list_pending returns { cards } from a fresh read. It does not use the sqlite table below.
The host polls that same route on a timer. TIMON_MCP_PENDING_INTERVAL_MS is the gap in milliseconds (default 5000, minimum 1000, maximum 60000). An empty value uses the default. Any other value refuses to start, with the text TIMON_MCP_PENDING_INTERVAL_MS is invalid. The first poll waits one interval. A tick that arrives while a pass is still reading is ignored. The pass enqueues webhook work and returns without waiting for a try, a retry, or a timeout. Card ids are stored in the host sqlite table host_pending_cards, so a restart does not send pending again for an id already recorded. Webhook occurrence counts are stored in host_pending_webhook_seq and stay when resolved rows are deleted. Resolved rows are kept up to 200 and the oldest are deleted past that. A card that was not stored, or that was stored as resolved and has come back, produces the event pending. A stored pending id that is absent from a complete list produces resolved, using the projection that was stored. An approval stored before command existed has no such key: the resolved webhook adds command: null, because the original command cannot be recovered. A stored question or kanban plan is sent unchanged and still has no command. A stored pending id that the list still contains, but that this host cannot project, stays pending and is not sent again. A projection that changed while the card is still pending is written back and is not sent again. A poll that fails, or a list of more than 200 cards, changes nothing: a missing tail must not look resolved. The log then says pending poll failed, pending poll too_large, or pending list is over the cap, and does not include the body. With no webhook URL the poll still records ids, and nothing is sent. A recorded id is not sent again as pending if a URL is set later. A resolved event can arrive for a card that was recorded before that URL was set, once the card leaves a complete list. A card that was never recorded does not produce resolved.
TIMON_MCP_PENDING_WEBHOOK_URL is that URL. Leave it unset or empty to send nothing. https is required. http is accepted only when the host is 127.0.0.1, localhost, or ::1. A userinfo, a query, a hash, a space, or a length past 2000 characters is refused before the process listens, with the text pending webhook URL is invalid. The message does not include the URL. Redirects are not followed: a 3xx is a failed attempt. TIMON_MCP_PENDING_WEBHOOK_SECRET is required when a URL is set. It is a string of 16 to 512 characters, read from the environment file, and it is never written to the repository, a test, a journal, or a log. A missing or unusable secret refuses to start with the text pending webhook secret is missing, and that text does not include the secret. The secret is not a settings key. A secret that starts with whsec_ is a Standard Webhooks secret: the host base64-decodes the characters after the prefix and uses those bytes as the key of webhook-signature. Those characters must be canonical base64 (alphabet A-Za-z0-9+/, = padding, and encoding the decoded bytes returns the same text). Otherwise the host refuses to start, with the text pending webhook secret is not valid base64, and that text does not include the secret. A secret that does not start with whsec_ uses its UTF-8 bytes as that key. x-timon-signature always uses the secret string as given, including a whsec_ prefix when one is present. It does not use the decoded bytes.
Each event is one POST of {"event":"pending"|"resolved","card":<projection>}. The headers are content-type: application/json, x-timon-timestamp (Unix milliseconds, decimal), and x-timon-signature (v1= plus the hex HMAC-SHA256 of ${timestamp}.${rawBody}, where rawBody is the exact bytes of the POST). The same POST also carries the Standard Webhooks headers. webhook-id is <event>_<card id>_<n>, for example pending_ followed by the card UUID and _1. n is a decimal count of that event for that card, starting at 1. Every attempt of one occurrence sends the same id. The next time that event is recorded for the card, the count is one higher, so pending, then resolved, then pending again are three ids, and a later resolved is a fourth. The counts are pending_seq and resolved_seq in host_pending_webhook_seq. They are written in the same transaction as the card row, and only once that occurrence's delivery tries have finished. A restart before that write sends the same occurrence again with the same id. A restart after it does not send the occurrence again. The value is the event name, the card id with control characters removed, underscores, and the decimal count, so it can be an HTTP header. x-timon-timestamp and x-timon-signature are unchanged. webhook-timestamp is that same clock reading, written as Unix seconds. webhook-signature is v1, plus the base64 HMAC-SHA256 of ${webhook-id}.${webhook-timestamp}.${rawBody}, using the key rule above. Each attempt takes a new timestamp and signs both headers again. The id does not change, and x-timon-timestamp stays the millisecond value: it is not rewritten from the seconds. The receiver should read the raw body, reject a timestamp more than five minutes from its clock, and compare with a constant-time check:
import { createHmac, timingSafeEqual } from 'node:crypto';
const MAX_SKEW_MS = 5 * 60 * 1000;
function verifyPendingWebhook(secret, rawBody, timestampHeader, signatureHeader) {
if (!/^[0-9]{1,16}$/.test(timestampHeader)) return false;
const timestamp = Number(timestampHeader);
if (!Number.isSafeInteger(timestamp) || Math.abs(Date.now() - timestamp) > MAX_SKEW_MS) return false;
const expected = createHmac('sha256', secret).update(`${timestampHeader}.${rawBody}`).digest('hex');
const got = signatureHeader.startsWith('v1=') ? signatureHeader.slice(3) : '';
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(got, 'hex');
return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
}The Standard Webhooks check uses the same body and the key rule above. Hermes Agent checks these headers (webhook-id, webhook-timestamp, webhook-signature):
import { createHmac, timingSafeEqual } from 'node:crypto';
const MAX_SKEW_S = 5 * 60;
function standardWebhookKey(secret) {
if (secret.startsWith('whsec_')) return Buffer.from(secret.slice('whsec_'.length), 'base64');
return Buffer.from(secret, 'utf8');
}
function verifyStandardWebhook(secret, rawBody, idHeader, timestampHeader, signatureHeader) {
if (!/^[0-9]{1,16}$/.test(timestampHeader)) return false;
const timestamp = Number(timestampHeader);
if (!Number.isSafeInteger(timestamp) || Math.abs(Math.floor(Date.now() / 1000) - timestamp) > MAX_SKEW_S) return false;
const expected = createHmac('sha256', standardWebhookKey(secret))
.update(`${idHeader}.${timestampHeader}.${rawBody}`)
.digest('base64');
const got = signatureHeader.startsWith('v1,') ? signatureHeader.slice(3) : '';
const a = Buffer.from(expected);
const b = Buffer.from(got);
return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
}Hermes Agent subscribes the route with the same secret. The command takes the route name, not a URL (hermes webhook subscribe --help):
hermes webhook subscribe <name> --secret <the same secret><name> is the route name. Hermes receives the POST at /webhooks/<name>. Set TIMON_MCP_PENDING_WEBHOOK_URL to that URL. Pass --secret: without it, Hermes generates a different secret. This package does not create the subscription.
Deliveries run on a separate queue. At most 4 run at once, and at most 32 are outstanding, waiting and in flight together. A card that does not fit is left unrecorded; a later poll tries it again. The log then says pending delivery queue is full, with no card body. A delivery is tried three times. The waits before the second and third tries are 200 ms and 800 ms. Each try stops after 5 seconds. The card is recorded after those tries finish, including when they fail, so a later poll does not send that event again. A restart before the record still sends it, with the same webhook-id. After the third failure the host logs pending webhook abandoned event=<event> id=<card id> and does not log the body, the URL, the secret, the decoded key, or a signature. The caller that receives the webhook is configured by the operator. This package does not wire that caller.
An example user unit is deploy/timon-mcp-standalone.service. It loads EnvironmentFile=-%h/.config/timon-mcp/standalone.env and contains no secret. deploy/timon-mcp-standalone.env.example lists the variable names, including the webhook URL, the webhook secret, and the poll interval, with no values. The operator copies it, fills the secret outside the repository, replaces ExecStart with the checkout (the program, host/ and lib/ stay together), and installs the unit. This package does not install it.
Answering a waiting card
answer_question answers a question or a kanban plan. resolve_approval allows or denies a tool approval. list_decisions reads the journal. None of the three is a plugin tool, none takes a spawn slot, and none is present when the plugin runs inside the daemon.
The card id is a lowercase UUID. answer_question takes answers (an object keyed by the question text; each choice is one of the offered options, and choices is accepted only on a multi-select question) or plan (mode, roles, and optional groups and note). An optional note on a question is trimmed and omitted when blank. cancel: true sends no answer. resolve_approval takes behavior allow or deny, and deny takes an optional message of at most 2000 characters. scope, paste, and updatedInput are not parameters. A call that names one of them, or any other field, is refused before the daemon is called. relay_channel is optional and defaults to hermes. It is the only accepted channel. decided_by is not a parameter.
Before it posts, the host reads GET /api/permissions and uses the card that is there now. A missing id is card not found. A question tool on an approval, or an approval tool on a question or a plan, is refused and nothing is posted. The body of POST /api/permissions/:id/resolve is then exactly one of:
{ "behavior": "allow" }{ "behavior": "deny" }or{ "behavior": "deny", "message": "..." }{ "behavior": "allow", "updatedInput": { "answers": {}, "note": "..." } }(noteonly when it has text){ "behavior": "allow", "updatedInput": { "plan": {} } }a cancel, which is
{ "behavior": "deny", "message": "<the form-cancelled text>" }
GET /api/auth/me runs only after that body is valid, and only to read user.id. A null user is recorded as daemon-token. Any other shape is refused with account id is unusable, and the resolve route is not called. The rest of /api/auth/me (the address, the name, the preferences) is not logged, not stored, and not returned by a tool. The host does not serve /api/auth/me.
The tool result is { id, type, status }. status is what the daemon accepted. { "ok": true } means the body above was accepted: an approval is allow or deny, a question or a plan is answered, and a cancel is cancelled. A behavior echoed by the daemon replaces the one that was sent. Anything else, including a non-200 that is not 404, is daemon refused the decision and is not journalled. 404 is card not found and is not journalled.
A successful decision is one row in host_decisions: the card id, the type (question, series_plan, approval), the status (allow, deny, answered, cancelled), the time, decided_by, and relayed_by. relayed_by is static:<channel> for the static bearer, or <subject>:<channel> where <subject> is the SHA-256 of the OAuth address already stored for that token. The address itself is not written. list_decisions returns those columns, newest first. limit is 1 to 100 and 50 when omitted. It does not call the daemon.
Answering does not write host_pending_cards and does not post the webhook. The next poll sees the card gone and emits resolved once, the same way a card that disappears for any other reason does.
Answering a card by hand
Check to run later against a daemon when a mission is started on purpose. Not part of npm test, and it does not use a live Hermes.
Start the standalone host against the local daemon, with the static bearer or an OAuth client.
Start a mission that asks a question or raises a tool approval.
Read
list_pending, or receive thependingwebhook.For a question or a kanban plan, call
answer_question. For a tool approval, callresolve_approvalwithallowordeny. Do not sendscope,paste, or a rewritten tool input.list_pendingno longer returns that id. The next poll emitsresolvedonce. The mission continues.list_decisionsshows the card id, the type, the status the daemon accepted,decided_by(the account id from the daemon, ordaemon-token), andrelayed_by(the OAuth subject digest, orstatic, plus the channel). The address is not in that row.
Wiring this to Hermes on Telegram is a later step and needs an explicit go-ahead. It is not done here.
Tests
No npm dependency: the stateless subset of MCP Streamable HTTP is a small JSON-RPC core in lib/mcp/. @timon-ai/sdk is not published. The contract tests (node:test) follow the documented daemon contract and use the fake context in test/helpers/fake-ctx.js. The SQL double in the tests uses node:sqlite. The plugin itself calls only ctx.sql.
The standalone host is covered by the same command. Those tests speak to an in-process fake daemon and do not call an installed daemon.
npm testDistribution check, from this directory:
timon plugin check .Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Streamable HTTP MCP server exposing planner flows, tasks, and squads.
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
Public Streamable HTTP MCP gateway for XGRChain, XDaLa sessions, Explorer data and XGR standards.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA minimal, containerized MCP server that exposes a Streamable HTTP transport with API key authentication, allowing secure access to MCP endpoints.-
- AlicenseNot gradedqualityDmaintenanceEnables MCP client interaction via streamable HTTP, providing example tools (echo, getPostsByUser) and resources (posts, users) with pluggable authentication providers.6MIT
- AlicenseNot gradedqualityBmaintenanceExposes AgentHansa's MCP tools to remote clients over Streamable HTTP, enabling ChatGPT and desktop agents to use the AgentHansa service through a secure authenticated endpoint.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible clients to securely interact with the BlogWarp REST API via Streamable HTTP, providing read-only access to posts, notifications, timeline, conversations, and following, plus mutating operations such as drafting, publishing, replying, following, and marking notifications read with explicit confirmation.MIT