CLI vs MCP
Why ContactCTL is a CLI, not an MCP server
Looking for a ContactCTL MCP server? There is none — on purpose. This page explains the trade-off honestly, shows how MCP-based agents use ContactCTL anyway, and names the cases where an MCP server is genuinely the right call.
01 — The short answer
The tool should cost nothing until it works
MCP is a good protocol that solves a real problem: giving models a standard, typed way to discover and call tools. We respect it — and we still chose a native CLI, because for contact data the economics point the other way.
An MCP server's tool schemas ride along in context for the whole session, whether or not
a tool is used. A CLI costs zero tokens until the moment your agent runs ctc instructions — about 60 lines, once — and from then
on each call is a short command. For a tool used a few times per session, the resident
schema is overhead with no payoff.
A CLI also starts in milliseconds, puts no server between the agent and the work, and composes with everything that already exists: pipes, files, cron, CI. Batch enrichment of a CSV with atomic writes and resumable runs is natural for a CLI — and would be an awkward fit for per-call tool invocations.
02 — Side by side
The trade-offs, stated plainly
| Property | Native CLI (ContactCTL) | MCP server |
|---|---|---|
| Context-window cost | Zero until used; ctc instructions is ~60 lines, read once per session | Tool schemas occupy context in every request while the server is connected |
| Startup | Native binary — runs in milliseconds | Server process or remote endpoint between agent and action |
| Composability | Pipes, files, cron, CI, Make — for free | Composition happens inside the agent loop |
| Failure surface | One binary and one HTTPS API | Agent + protocol client + server + API |
| Works without an agent | Yes — humans and shell scripts use the same tool | Designed for model-driven calls |
| Typed tool discovery | Conventions: --help, --json, exit codes | First-class: schemas advertised to the model automatically |
Neither column wins everywhere. For a focused, occasionally-called, batch-heavy tool like contact data, the CLI column is the better fit.
03 — Using it from an MCP stack
Your MCP-based agent can run it today
MCP and ContactCTL are not in conflict. Agents built around MCP — Claude Code, Codex
CLI, Cursor, Gemini CLI, and most custom stacks — also expose a shell or command tool,
and that is the only capability ContactCTL needs. Keep your MCP servers for what they
are good at; run ctc beside them.
Setup per tool, with context-file snippets, is on the integrations page. The complete command reference is in the docs.
npm install -g contactctl contactctl auth <api_key> # key from the dashboard # then, in the agent's context file or first message: # "Use the ctc CLI for contact data. # Run `ctc instructions` before first use."
04 — Fair is fair
When MCP is the right choice
MCP earns its overhead when tools are called constantly within a session, when typed schema discovery genuinely prevents misuse, when the tool needs stateful back-and-forth rather than one-shot commands, or when the agent runs in a sandbox that cannot execute binaries at all. Long-lived connections to databases, browsers, or design tools are classic good fits. If your tool looks like that, build it as an MCP server — ours does not, so we did not.
FAQ
Common questions
Is there a ContactCTL MCP server?
No, and that is a deliberate product decision rather than a missing feature. The CLI delivers the same capabilities with zero standing context cost and fewer moving parts. If your stack is MCP-based, your agent can still run ContactCTL through its shell or command tool.
My agent only speaks MCP — can it still use ContactCTL?
Almost every MCP-capable agent also has a shell/Bash/command tool, and that is all ContactCTL needs. Point the agent at `ctc instructions` and it can operate the tool from there. If your environment truly cannot execute commands, the HTTPS API on /api is the fallback.
Does using a CLI instead of MCP cost me capability?
You give up automatic schema advertisement — the agent must read instructions once instead. You keep everything else: structured JSON output, deterministic behavior, cost previews, and batch semantics that MCP tool calls would have to reimplement.
Will ContactCTL add an MCP server later?
If the trade-offs change — for example, if context costs of resident schemas stop mattering — we would revisit it. The HTTPS API underneath is surface-agnostic, so adding one would not change the product you build on today.