Agent Surface MCP server

Agent Surface

Agent Surface is a field guide and implementation kit for engineering teams making software operable by agents: discoverable, understandable, callable, recoverable, and evaluable.

Agents do not reach software through one interface. They read docs, inspect repositories, call APIs, run CLIs, use MCP tools, parse errors, and retrieve data. Agent Surface treats all of those contact points as one design problem: the agent surface.

Two Parts

The site has two labelled parts.

Part 1 - Make your product agent-ready (the core guide). Product-side, framework-neutral guidance for making an existing product usable by agents: discovery, API surface, tool design, CLI design, MCP servers, authentication, error handling, context files (AGENTS.md/CLAUDE.md), agentic UI, retrievability (search APIs, retrieval contracts, structured content), protocols, testing, scoring, and reference links. This is the guide the surface skill applies.

Part 2 - Build agents (the agent-building inventory). A secondary, condensed reference for teams building their own agents: frameworks (including Mastra), platform features, orchestration, memory, durable execution, browser and sandbox access, guardrails (/docs/agents), and agent retrieval - vector databases, embeddings, RAG, knowledge graphs (/docs/agent-retrieval) - plus a tooling catalog. This inventory gives one short summary of current practice per topic; it sits outside the core guide and outside the surface skill.

An earlier version of this repo kept agent-internal architecture out entirely. We keep the inventory because it is worth maintaining as a reference, but it stays separate so the guide does not turn into a general agent-building toolkit.

The surface Skill

surface is a single skill with three routes, all product-side and framework-neutral:

the right doc or primary source.

• Guide - explain agent-surface concepts, standards, and implementation patterns; point to

findings, and write a transformation plan. plan and transform are Audit modes, not separate routes; transform executes only after explicit confirmation.

• Audit - detect a project's surfaces, score agent readiness across 10 dimensions, produce

contracts, retrieval endpoints) and the evaluation harnesses that verify them. It does not generate agent-internal architecture (agents, orchestration, memory, model routing, an agent's own retrieval pipeline) - that belongs to Part 2, not this skill.

• Scaffold - create or extend agent surfaces (discovery files, API/CLI/MCP surfaces, tool

The 10 audit dimensions:

1. API Surface
2. CLI Design
3. MCP Server
4. Discovery and AEO
5. Authentication
6. Error Handling
7. Tool Design
8. Context Files
9. Testing and Evaluation
10. Retrievability

See skills/surface/SKILL.md for the operative workflow and skills/surface/references/ for the per-dimension and per-mode detail.

Repository Contents

• skills/surface/ - skill entrypoint, audit/scaffold references, and specialist agent prompts
• src/content/docs/ - the two-part MDX guide served by the docs site
• disciplines/ - longer-form guidance on agent-surface design topics
• templates/ - reusable starter files the implementation kit points to
• src/app/ - Next.js application for the docs site
• docs/ - ADRs and internal supporting documents

Quick Start

Prerequisites:

• Node 24.15+
• pnpm 11

Install and run the docs site:

pnpm install
pnpm dev

Other useful commands:

pnpm build
pnpm start
pnpm test        # docs integrity check
pnpm typecheck
pnpm lint

Notes:

Shortened. The full README is on GitHub.