How to give AI agents real work: MCP + Structured Specs explained

There's a gap between "AI can write code" and "AI can build what the team actually needs." That gap is context delivery.

Today, most teams deliver context to AI agents through copy-paste: grab text from Jira, Notion, Slack, or a Google Doc, paste it into the chat window, and hope the agent understands. This is the software equivalent of whispering instructions across a noisy room.

MCP (Model Context Protocol) + Structured Specs is the alternative: a direct, lossless pipeline from your team's decisions to your AI agent's context window.

What is MCP?

The Model Context Protocol is an open standard created by Anthropic for connecting AI models to external tools and data sources. Think of it as a USB port for AI agents — a standardized interface that any tool can plug into.

MCP defines three primitives:

• Tools — Functions the AI can call (read data, perform actions)
• Resources — Data the AI can access (files, databases, APIs)
• Prompts — Templated instructions for common workflows

When an AI agent connects to an MCP server, it gains access to that server's tools and resources. No copy-pasting. No context windows full of unstructured text.

The problem with unstructured context

When you paste a Notion doc into Claude Code, several things go wrong:

1. Format loss — Rich formatting, tables, and structure flatten into plain text
2. Context truncation — Long docs get cut off at the context window limit
3. Signal dilution — Meeting notes, discussion history, and other noise dilute the actual requirements
4. Version drift — The pasted text is a snapshot. The real spec may have changed since you pasted it.
5. No feedback loop — The agent can't write back to the spec or update task status

MCP solves all five problems.

How Colign's MCP server works

Colign exposes a set of MCP tools that AI agents can call:

``` list_projects → Discover available projects get_change → Get change metadata and workflow state read_spec → Fetch proposal, design, or spec (structured JSON) write_spec → Update proposal or design sections list_tasks → Get all tasks for a change update_task → Mark tasks todo/in_progress/done suggest_spec → Get AI suggestions for spec improvement list_acceptance_criteria → Fetch Given/When/Then scenarios create_acceptance_criteria → Create new scenarios ```

The key difference from a generic API: these tools return structured data optimized for AI consumption. A `read_spec` call returns JSON with clearly separated Problem, Scope, Out of Scope, and Approach sections — not a blob of markdown.

The full pipeline

Here's how MCP + Structured Specs creates a reliable spec-to-code pipeline:

1. Team writes spec in Colign

• Problem, Scope, Out of Scope, Approach
• Acceptance criteria in Given/When/Then
• Real-time co-editing, inline comments

2. Team reviews and approves

• Workflow gates ensure all approvers sign off
• Spec becomes immutable after approval

3. AI agent reads spec via MCP ``` → read_spec(change_id, section: "proposal") ← { problem: "...", scope: [...], out_of_scope: [...], approach: [...] }

→ list_acceptance_criteria(change_id) ← [{ given: "...", when: "...", then: "..." }, ...]

→ list_tasks(change_id) ← [{ title: "...", status: "todo", description: "..." }, ...] ```

4. AI agent implements and reports progress ``` → update_task(task_id, status: "in_progress") → [writes code] → update_task(task_id, status: "done") ```

5. Team sees progress in real-time

• Tasks update on the Colign dashboard
• The spec remains the source of truth

Why this beats copy-paste

| Copy-Paste Workflow | MCP + Structured Spec | |--------------------|----------------------| | Manual, error-prone | Automated, reliable | | Lossy (format, context) | Lossless (structured JSON) | | Snapshot in time | Always reads latest version | | One-way (human → agent) | Two-way (agent reads AND writes) | | No progress tracking | Real-time task updates |

Getting started

Two deployment options for Colign's MCP server:

Streamable HTTP (SaaS — recommended): ```json { "mcpServers": { "colign": { "type": "streamableHttp", "url": "https://mcp.colign.dev" } } } ```

stdio (self-hosted): ```json { "mcpServers": { "colign": { "command": "colign-mcp", "args": ["--api-url", "https://your-instance.com"] } } } ```

Once connected, your AI agent has direct, structured access to every spec in your project.

FAQ

Q: Is MCP specific to Claude/Anthropic? A: No. MCP is an open standard. Any AI tool can implement MCP support. Cursor, VS Code extensions, and custom agents can all connect.

Q: What about security? Can the AI agent modify specs? A: Access is controlled via API tokens with scoped permissions. You can grant read-only access to agents and write access only to specific tools.

Q: Does this work offline? A: The stdio mode runs a local binary that connects to your Colign instance. If your instance is self-hosted on your network, it works without internet access.