MCP Servers & Assistant Integration
- ·A server that publishes what a system already knows, so an assistant can query it directly instead of scraping a rendered page.
- ·Every tool result carries the address it came from, which is what lets an assistant cite the source rather than paraphrase it.
- ·This site is its own example, and the tests that pin what each tool returns run in the same suite as everything else.
| Built with | Model Context Protocol · TypeScript · Next.js · Vercel |
| Delivered by | mcp-engineer · agentic-director · |
| Skills used | mcp-builder · agents-sdk |
Receipts
What this involves
Most sites are readable by an assistant only in the sense that they can be scraped: the assistant fetches rendered HTML, guesses at the structure, and paraphrases. A Model Context Protocol server replaces that with a query. The assistant asks for projects, or services, or the career record, and gets back the same structured record the site itself renders from.
This site is the worked example. It publishes itself at /api/mcp over Streamable HTTP, every tool result carries the canonical URL it came from so an assistant can cite the page rather than paraphrase the site, and the tests that pin what each tool returns run in the same -test suite as everything else.
The second receipt is the part that is easy to get wrong. snapgauge is a contract-test tool for MCP servers, built after finding that a tool description edit is schema-valid, passes every validator, and still changes which tool a model picks. It grades that edit as risky rather than cosmetic, and its 37 golden and compat cases at 100% exact match hold the grading in place. A server without something like it ships a breaking change every time somebody improves the wording.
The work on an engagement is the surface design before it is the code: which tools exist, what each one is allowed to see, what it returns, and what happens when the model asks for something it should not have. A server that exposes a database is a security review, not an integration.
A tool description edit is schema-valid, passes every validator, and still changes which tool a model picks. That is the failure contract tests exist to catch.
How the work runs
1. Discovery
We agree what the project has to achieve, what it must not break, and how we will both know it worked, before any code is written.
2. Build
The work is built with an AI agent as the working partner and a human reviewing every change before it lands. You get commits you can read rather than a status update.
3. Review
You review running software at each milestone, not a screenshot of it, and the next milestone absorbs what you send back.
4. Launch
We deploy to production with checks in the pipeline and alerting that reaches a human, and you hold the repository and the infrastructure accounts.
Questions people actually ask
What does an MCP server give me that an API does not?
An API is for a programmer who reads your documentation. An MCP server is for an assistant that discovers your tools at connection time and decides which to call. The difference in practice is the tool descriptions: they are prompt text, they steer selection, and they need version control and tests for the same reason a schema does.
Can an assistant change things, or only read them?
Either, and the decision belongs in the scope document rather than in the implementation. Read-only is the safe default and covers most of the value. A tool that writes needs the same treatment as any other endpoint that writes: an authorisation model, an audit trail, and a clear answer to what happens when it is called twice.
How do I check that this site's server is real rather than described?
Connect to it. The endpoint is /api/mcp on this domain, it speaks Streamable HTTP, and the `connect` command on this console prints the configuration for the common clients. Every tool result includes the canonical URL its content came from, so anything an assistant tells you about James can be checked against the page it was read from.