Context Over MCP, Series Wrap: Six Lessons, FAQs, and What I'd Do Differently

Seven pieces, one question: how does an agent get your project's context when it has no working directory?

AGENTS.md works because a coding agent opens your repo and reads a file. Connect that same agent to a project over MCP, or put a tool in a browser tab, and there's no folder to read. The instructions are still true. The agent just can't see them.

This wrap is the map, the six lessons, a few FAQs, and what I'd do differently.

The map

Part	Title	Read it if…
I	Invisible AGENTS.md? Meet the visible MCP context card	you want the problem in one page
II	Publishing an MCP server to the official Registry (and the parts nobody writes down)	you're about to publish a server
III	Horses for Courses	you're deciding what goes in prose and what goes in data
IV	No Working Directory At All	your client is a browser tab
Companion	Build a WebMCP Tool From Scratch	you'd rather build one than read about it
V	The Form Is the Tool	you have HTML forms and no time for script
VI	Context You Can See	you want to see what your agent sees

Six lessons

1. A file convention doesn't travel over a protocol. AGENTS.md is a filesystem convention. An MCP client has no working directory, so it never finds the file. The fix isn't a new file. It's serving the same context through MCP: tools and resources the client can call, discoverable from the server's metadata. (Part I)

2. Publishing is where the undocumented failures live. The official Registry is straightforward until it isn't: a case-sensitive login match, a 100-character server.json description cap, and versions drifting between the package and the registry entry. Automating the publish with GitHub Actions OIDC removes most of it. (Part II)

3. Prose for instructions, data for facts. Instructions read best as prose. Facts (versions, commands, paths) drift unless they're structured and checked. Keep them apart and derive one from the other, and a drift bug becomes a failed check instead of a confident wrong answer. (Part III)

4. The browser has no working directory either. With WebMCP, a page registers tools for an in-browser agent: document.modelContext.registerTool() natively, or a polyfill. The rules that kept it safe were small and boring: mark read-only tools readOnlyHint, return errors as data, and allowlist every fetch (exact host, HTTPS, no redirects). (Part IV and the companion)

5. A form can be the tool. Declarative WebMCP turns an existing HTML form into a tool with a few attributes, no script, and the human still confirms the submit. If your site already has forms, you're most of the way there. (Part V)

6. Context should be visible. If an agent works from context, you should be able to see that context. Part VI shows it as a card: inline as an MCP App where the host supports it, as text plus a browser view where it doesn't, and with no config by reading the project from MCP roots. Shown in goose and in the MCP Apps reference host. (Part VI)

One rename: "server card" → "context card"

Part I called it a "visible MCP server card". That name was a mistake I'll own. MCP Server Cards are a separate, spec-level idea: metadata that describes a server. What Part I meant, and what Part VI shows, is the context card: the project context an agent actually sees. From here on it's "context card" everywhere.

Works with Skills over MCP

Skills over MCP (SEP-2640) lets an MCP server serve its skills right alongside its tools, as skill:// resources the agent loads when they're relevant. Angie Jones put the idea in one line:

"Essentially, ship the manual with the product."
Angie Jones, Skills Over MCP

So the agent has the tools, and now it has the manual. One question is still open: what are we building, for whom, and why?

That's project context, and it's what Context over MCP serves: the AGENTS.md rules, memory and identity the agent would have read from disk if it had a working directory. Tools say what the agent can do. Skills say how. Context says what, for whom and why.

Skills over MCP ships the manual for the tools. Context over MCP ships the facts about your project. An agent needs both to do the right thing in the right place.

It's timely, too. Agent Skills, the SKILL.md format, is on its way to becoming an AAIF project, and AAIF has already called MCP and Skills "the two halves of a working agent". Project context is what tells those two halves where they are.

Skills + Context over MCP = an agent informed and ready.

FAQs

Does this replace AGENTS.md? No. AGENTS.md stays the source. Everything here is about getting the same context to agents that can't open the file.

My agent reads AGENTS.md fine. Do I need any of this? Not for a local coding agent in your repo. It matters when the agent reaches your project over MCP, from another machine, or from a browser.

Which clients show the card inline? Hosts that support MCP Apps render it inline; Part VI shows it in the MCP Apps reference host. Elsewhere you get the text card and a browser view, which is how Part VI shows it in goose.

Is WebMCP in every browser? No. Chrome has native support behind a flag (Parts IV and V ran in Chrome 153 with it on). Elsewhere, the polyfill covers it.

Stateless or stateful? The context card server runs over stdio and stateless Streamable HTTP, which keeps it simple to host. The WebMCP pieces run in the browser tab itself.

What I'd do differently

• Name things once. The "server card" slip cost a rename. Check a name against the spec vocabulary before it goes in a title.
• Lead with the picture. Part VI's card made the whole series click for readers. I'd show it in Part I.
• Ship the tutorials first. The how-to pieces travelled further than the explanations. A run-it-yourself version of every idea, from the start.

What's next

A goose docs contribution for the context card is next, so the extension setup lives where goose users already look.

Thanks for reading along. Questions and corrections are welcome in the comments.