This reference describes the MCP server and its current source-level contracts. For installation, client setup, and human approval workflows, see the MCP Server User Guide. The runtime tools/list, resources/templates/list, and prompts/list catalogs are authoritative for the particular binary being used. Limits, availability, and schemas can change between builds.
MCP client <-- UTF-8 JSON-RPC over stdio --> TCMcpServer.exe
|
authenticated local named pipe, on demand
|
Take Command
|
approved session, TCC and local data
TCMcpServer.exe is a local stdio MCP server, not an HTTP listener. It can answer local help and syntax requests without a host connection. For host operations, Take Command owns the pipe, sessions, profile policy, consent UI, and the final authorization decision. The server discovers candidate hosts only on request; an instance ID is a selection hint, not a credential.
The host's pipe is \\.\pipe\TakeCommand.McpBroker.<TakeCommand PID>, with remote clients rejected and access restricted to the interactive user. Host discovery and registration check the live process identity and creation time, Windows user, session and integrity, and the expected signed images and protected installation. Registration requires visible approval. The host delivers a per-connection capability only after the applicable checks and approval; directional keys authenticate subsequent bounded frames, request IDs, and sequence numbers. The initial capability handoff is not independently authenticated by its zero MAC: the client must first verify and pin the host. One client is registered per host at a time.
These controls do not establish which upstream model or user initiated an MCP request, nor do they isolate the product from other processes running as the same Windows user. Administrator and same-user process attacks are not solved by visible consent or executable signing. Terminal output, help, repository paths, tool output, and all other retrieved content are untrusted data, not instructions for the client.
•Start the installed TCMcpServer.exe directly with stdio pipes. Requests and responses are UTF-8 JSON-RPC 2.0 objects, one per line; reserve stdout for protocol messages. Diagnostics belong on stderr, not stdout.
•Send initialize with a nonempty protocolVersion, read the server's response, and send notifications/initialized before other requests. The current server reports protocol version 2025-06-18; use the returned version rather than assuming it echoed the requested version.
•The current capabilities advertise tools, resources, prompts and completions. Catalog change notifications and resource subscriptions are not advertised. Use tools/list and the other catalog methods rather than assuming a fixed client-side list.
•The server permits one pending broker-backed request per stdio process. ping can proceed while one is pending; another distinct request receives -32000. A matching notifications/cancelled request ID cancels pending work; cancellation can close the reusable context. Do not retry a cancelled action as though it had necessarily had no effect.
•Terminating the server or closing stdin ends its connection. A host allows one registration attempt per server process; after closure or denial, start a fresh process and obtain fresh approval.
The server reads at most 1 MiB per incoming stdio line. The private broker's frame limits are 64 KiB for requests, 256 KiB for responses, and 512 bytes for registration; individual operation limits can be smaller. The broker protocol is internal and is not an alternative public MCP transport.
The following are three separate lines sent to stdin, in order. The first and third have responses; notifications/initialized does not. This example does not register with a host or request terminal access.
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_server_health","arguments":{}}}
The health tool's result.content[0].text is itself a JSON-encoded string:
{"version":"0.1.0","instanceId":"<server-pid>:<creation-time>","readOnly":false,"brokerAvailable":false,"brokerStatus":"on-demand-approval-required"}
Parse the outer JSON-RPC response and then the text content. The server launch ID above is not a host instance ID or an authorization token. readOnly:false describes the server's consent-gated actions; local TCC context's separate read-only flags do not describe the entire server. Some schema-declaring tools also return the same JSON in structuredContent; inspect the advertised schema rather than assuming every tool does so.
Errors can be JSON-RPC errors or tool results with isError:true. Examples include -32700 for invalid UTF-8 or JSON, -32600 for an invalid request, -32601 for an unknown method, -32602 for invalid arguments, -32603 for an internal/resource error, -32002 before initialization, and -32800 for cancelled work. A generic refusal does not establish a particular policy or failure cause, and a successful response is not a guarantee of complete data.
list_broker_hosts returns public host instance IDs. probe_broker_health, get_active_terminal_metadata, and list_terminal_sessions use distinct one-shot registrations; handles from the one-shot session list cannot be used for later reads. open_terminal_context instead establishes an explicitly approved reusable connection and returns:
{"sessions":[{"handle":"0123456789abcdef0123456789abcdef","kind":"conpty","state":"active","readOnly":false}],"hasMore":false}
The handle above is illustrative. Actual handles are opaque 32-character lowercase hexadecimal values, bound to the approved client, connection and session, and must not be copied to another server process. active describes session state; it does not identify the selected tab. Context sharing requires approval of the listed sessions and their metadata-enabled profiles. The host scans at most 128 documents and returns at most 32 eligible sessions, otherwise it fails closed. Context lifetime is bounded by a 30-minute lease and can end earlier on idle expiry, policy changes, cancellation, revocation, disconnect, focus or session invalidation, or peer exit. close_terminal_context revokes its handles; closing an already absent context succeeds.
Profile policy is a prerequisite, not consent. The policy keys are McpShareMetadata, McpShareTranscript, McpShareTranscriptText, McpShareRepositoryIndex, McpAllowReviewActions, McpAllowRecordingControl, McpAllowInputControl, and McpAllowCommandExecution. They are independently default-off. Text requires both transcript policies; repository-index policy does not grant transcript access. Sensitive reads and each action require their own approval in addition to the context. Revalidation occurs before disclosure or action; a stale session, policy, content, path, or approval can cause refusal.
The tables summarize the 30 tools exposed by the current catalog. Required arguments are shown without a suffix; ? means optional. For exact JSON schemas and descriptions, use tools/list. All tool input objects reject additional properties. handle denotes an approved reusable context handle; instanceId denotes the selected host from list_broker_hosts.
Tool |
Arguments |
Result and scope |
|---|---|---|
get_server_health |
none |
Server version, launch ID, capability flags and current broker status. |
get_tcc_context |
none |
Local help availability and local-context flags; no installation path. |
list_broker_hosts |
none |
Verified host selection hints and broker status; no authorization. |
is_registered_tcc_internal |
command |
Whether a bare name is registered in the adjacent TCC DLL; not live resolution. |
describe_tcc_internal_command |
command |
Registration and static parse attributes, not runtime resolution. |
get_tcc_command_help |
command |
Installed help for a validated command name, bounded to 64 KiB. |
list_tcc_help_topics |
prefix?, after?, limit? |
Paged installed help-topic names; limit is 1-50. |
analyze_tcc_syntax |
command |
Non-executing lexical spans and counts under fixed default settings. |
analyze_tcc_redirections |
command |
Redirection source candidates and UTF-16 spans, not resolved targets. |
analyze_tcc_expansion_syntax |
command |
Expansion source candidates and spans, without evaluation or values. |
analyze_tcc_command_structure |
command |
Bounded source command and connector candidates, including supported nested attachments. |
analyze_tcc_grouped_command_structure |
command, includeRedirections? |
Supported grouped/nested source topology and optional redirection annotations. |
Syntax-analysis command inputs are bounded to 4096 UTF-16 code units. They report source structure, not the result of evaluating shell state, aliases, environment variables, executable lookup, or arbitrary runtime behavior. The internal registration queries accept a bare name of at most 31 ASCII letters, digits, _ or -; the help query uses a validated command name of at most 128 characters. Schema and implementation checks can impose further restrictions.
Tool |
Arguments |
Result and approval |
probe_broker_health |
instanceId |
One approved broker-health exchange; no terminal data. |
get_active_terminal_metadata |
instanceId |
One approved active-session metadata entry. |
list_terminal_sessions |
instanceId |
One-shot approved metadata for all eligible listed sessions; returned handles expire with the connection. |
open_terminal_context |
instanceId |
Registration and all-listed-session approval; returns reusable session handles. |
get_terminal_session |
handle |
One revalidated metadata entry in the same sessions envelope. |
close_terminal_context |
none |
Closes the connection and returns { "closed": true }. |
Metadata entries contain handle, kind, state, and readOnly, not tab titles, profile names, working directories, or terminal content. Each host exchange remains subject to identity, policy, consent, and lifetime checks.
Tool |
Arguments |
Returned information and prerequisite |
|---|---|---|
get_command_blocks |
handle |
{blocks:[{startRow,endRow,state,exitCode,durationMs}]}; transcript policy and per-read approval. |
list_command_blocks |
handle, cursor? |
Paged typed blocks plus sourceRange, pendingRange, unanchoredRange, hasMore, and nextCursor; per-page approval. |
read_terminal_text |
handle, firstRow, rowCount |
{firstRow,rowCount,filter:"heuristic",rows}; both transcript policies and per-read approval. |
search_terminal_scrollback |
handle, query |
Matching row/text pairs, scanned range, withheldRows, truncated, and filter; both transcript policies and per-search approval. |
get_active_selection |
handle |
Same page shape as terminal text for a settled selection; both transcript policies and per-read approval. |
get_repository_context |
handle |
Counts from the reported directory's Git index; index policy and per-request approval. |
get_changed_files |
handle |
Bounded tracked-file index-stat comparison with counts and {path,status} entries; index policy and per-request approval. |
resolve_tcc_command |
handle, command |
{source,name,category,path?} for a bare prompt word; index policy and per-request approval on an eligible idle local TCC tab. |
request_open_changed_files |
handle, paths |
Opens approved read-only review tabs and returns {opened:N}; review-action policy and approval. |
Command block rows are buffer-relative and inclusive; adjacent blocks can share boundaries. incomplete is not proof of a running process and unknown exit code/duration is null. A page scans at most 4096 rows, returns at most 32 blocks/8 KiB, and can be empty while hasMore is true. Cursors are single-use, expire after 60 seconds, and are limited to 32 outstanding per connection. Snapshot changes deny continuation.
Text reads accept 1-256 rows and at most 32 KiB of text; the encoded page is bounded to 64 KiB. Search accepts a 1-32-character printable ASCII query without quote or backslash, scans the newest 1024 rows, and returns at most 16 matches. The filter is heuristic, including checks of neighboring text; it may withhold safe data and may miss secrets. A positive classification is not proof that the data is safe. Text and typed-command reads share a 4 MiB per-connection budget; charges occur before response writes, so a failed or cancelled write does not refund a charge.
Repository operations use the .git directory directly in the tab-reported directory on eligible local fixed NTFS/ReFS storage. The index summary contains counts only, no path or contents. The changed-file result is a stat-based estimate of already tracked files, not a Git diff: staged and untracked changes, renames, and contents are not evaluated; same-size same-second changes can be missed. It returns at most 64 paths and reports omissions and skipped/racy entries. Review paths are client-proposed, not guaranteed changed; they must be 1-8 unique safe relative paths. The approval card shows the root, files and sizes. Each file must be eligible UTF-8/ASCII text, at most 256 KiB; the tool returns a count rather than the file content.
For example, after the appropriate approvals, the JSON in a successful tool's text content can have these shapes (values are illustrative):
{"blocks":[{"startRow":10,"endRow":15,"state":"completed","exitCode":0,"durationMs":125}]}
{"firstRow":10,"rowCount":2,"filter":"heuristic","rows":["plain text",""]}
{"source":"git-index-stat","scope":"tracked-files","staged":"not_evaluated","untracked":"not_evaluated","checked":5,"skipped":0,"racy":0,"modified":1,"deleted":0,"typeChanged":0,"conflicted":0,"omitted":0,"files":[{"path":"src/example.cpp","status":"modified"}]}
get_repository_context returns source:"git-index", worktree:"not_evaluated", and an index object containing version, entries, distinctPaths, stageEntries (four counts), conflictPaths, regularEntries, symlinkEntries, gitlinkEntries, intentToAddEntries, skipWorktreeEntries, assumeValidEntries, and optionalExtensions. Resolution returns source:"tcc-prompt-resolution" with name and a category of alias, library, plugin, internal, external, batch, or not_found; path appears only for external and batch.
Tool |
Arguments |
Success result and important limits |
|---|---|---|
request_start_recording |
handle |
{recording:"started"}; output only, create-new host-chosen file, 8 MiB or 10 minutes. |
request_send_terminal_input |
handle, text, enter? |
{input:"sent"}; 1-256 permitted Unicode characters, optional Enter, no returned output. |
request_run_tcc_command |
handle, command |
{run:{...}}; 1-1024 permitted Unicode characters, separate noninteractive process, default 10-second run timeout. |
All three require their own default-off policy and a fresh approval, and refuse unsupported session classes. Recording does not include keyboard input or shell-integration metadata, but its terminal output is unredacted and can contain secrets. Its path and contents are not returned by the tool. A timer checks idle recordings; delivery can be delayed by a busy UI thread.
Input forbids control characters, escape sequences, tabs, line breaks, invisible and direction-changing format characters. It goes to the tab's current input recipient; with Enter it can execute a command or submit input to a prompt. The consent card displays the text and Enter choice.
Command execution is arbitrary execution as the user, not a sandbox. The host analyzes the line, displays its source, resolved commands and working directory, and revalidates before launch. Alias-resolved heads, unsupported control flow, plugin/library commands, unresolved or unsafe paths, non-default parsing settings, more than eight distinct command words, and a non-idle tab are refused. Accepted heads are bound to approved targets and bypass alias lookup. Arguments and TCC expansion remain meaningful; the child uses normal startup and the host process environment, not the tab's environment. The runner uses a job object, separate output streams, and a timeout. Its response contains exitCode (null on timeout), timedOut, stragglersKilled, startupSeparated, startupStdout, startupStderr, startupTruncated, stdout, stderr, stdoutTruncated, and stderrTruncated. Output is not redacted; each main stream is capped at 64 KiB before conversion, startup at 8 KiB per stream, and the encoded response has a 200 KiB budget. A lost or denied reply cannot undo an action that has already occurred.
resources/list exposes takecommand://tcc/context. The current resource templates are:
URI template |
Content and authorization |
|---|---|
takecommand://tcc/help/{command} |
Installed local HTML help. |
takecommand://tabs/{handle} |
Approved reusable session metadata. |
takecommand://tabs/{handle}/commands |
Approved newest typed command blocks, with separate transcript consent. |
takecommand://tabs/{handle}/scrollback/{firstRow}/{rowCount} |
Approved text range, same policy and filtering as read_terminal_text. |
takecommand://tabs/{handle}/selection |
Approved selection, same policy and filtering as get_active_selection. |
takecommand://tabs/{handle}/repository |
Approved repository index summary. |
takecommand://tabs/{handle}/changes |
Approved tracked-file change estimate. |
Resources do not implicitly open contexts or grant access. A range uses canonical unsigned decimal row values and 1-256 rows. Resource content is returned in the MCP contents envelope; JSON resource content is itself a JSON string in text. Text resource results use a separate escaped-result cap because encoding may increase their size.
The six advertised prompts are prepare_tcc_command_explanation, prepare_tcc_source_review, summarize_recent_command_blocks, review_recent_command_failure, summarize_repository_changes, and plan_changed_files_review. The first accepts a command name; the second accepts a source command and optional string includeRedirections of "true" or "false". The other four require an existing handle and the same independent approval as the underlying read. Prompts do not grant authority to execute commands or implicitly open a context.
The installed server normally discovers help under <install-root>\help\CMDebug\html. For a nonstandard layout, set TCMCP_HELP_ROOT in the server process environment to the help directory. Help names are validated; reparse-point help files are not followed. Avoid writing diagnostics to stdout.
Tools > MCP Activity displays connection status and a bounded in-memory audit history. Revoke cancels pending approval or closes active access. For command-run diagnosis, if %TEMP%\TakeCommandMcpRun.log already exists, TCMD and the server append opt-in trace markers; TCMD also writes markers to the debugger. This trace is not a transcript or command-output log. Protect diagnostic files appropriately and remove the opt-in file when no longer needed.