Agent success depends on agent-ready repos and MCP tool wiring, not just stronger models

Why MCP Hookups, Not Just Models, enable Agent Potential in Production

The unsexy part of the agent story is the part that decides whether it ships or stalls. Frontier models can plan, refactor, write tests, and read your codebase. What they can't do, on their own, is reach your real services. They don't know your Postgres schema, can't tail your deploy logs, can't hit your auth provider. Without a connection to the world outside the editor, the agent is a brilliant writer in a sealed room. Model Context Protocol is the part that opens the door. It's a standardized handshake between an agent and a tool — one spec, one discovery mechanism, one call shape. The ecosystem is filling in around it fast: Stripe, Postgres, Sentry, Cloudflare, Linear, Notion, all of them. A server written once works in Cursor, Claude Code, Continue, Windsurf, and whatever ships next year. That part deserves to be celebrated, not waved off. The hard part isn't the spec. The hard part is wiring it into your repo so the agent can reach the five tools that actually matter on day one. How to wire MCP into an agent today The mechanics are simple. You run an MCP server — usually a local process — and tell the agent where it lives. The server exposes tools with JSON-Schema inputs. The agent discovers them at startup, picks the right one, and calls it. For Claude Code, the config lives in .mcp.json at the repo root: { "mcpServers": { "stripe": { "command": "npx", "args": ["-y", "@stripe/mcp"], "env": { "STRIPE_SECRET_KEY": "${env:STRIPE_SECRET_KEY}" } }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "${env:DATABASE_URL}" } } } } For Cursor, the same shape lives under "MCP Servers" in settings. For Windsurf, a ~/.codeium/windsurf/mcp_config.json. One file, one shape. The model just needs to be told the tools exist — the protocol handles the discovery. That's the floor. Anything more interesting than that floor is where the agent stops being a demo and starts being a teammate. [[DIAGRAM: agent loop — client discovers tools, calls them, reads results, continues; tools are local MCP servers reaching real services behind an env-gated boundary]] What "pre-wired" actually means A kit that ships "with MCP support" is doing four things, and only the fourth is interesting: Pinning the right server versions so a fresh clone just works. Wiring the env vars from a single .env.local instead of a config rabbit hole. Writing the prompts that teach the agent when to use which tool. Picking the small set of tools the agent will actually need in a real app — and omitting the rest. The first three are table stakes. The fourth is the enable. A blank MCP catalog with 200 servers is a worse starting point than a curated set of five. The agent's context window is finite. Every tool listed is a tool the model has to decide about, weigh against the others, and possibly misfire on. Curation is the feature. The five tools a production kit should ship Here's the minimum set a SaaS kit should expose on day one, in priority order: Database — read schema, run a query, explain a plan. Without this, the agent writes migrations blind. Payments — list products, create a price, attach a webhook, read the last 50 events. Without this, the agent can't verify a checkout. Deploy — list environments, tail logs, trigger a redeploy, roll back. Without this, "ship it" is a manual hop. Auth — list users, create a user, impersonate for debugging, revoke a session. Without this, the agent can't test login flows end-to-end. Email — send a templated message, list the last 20 sends, read the bounce report. Without this, password resets and onboarding flows are unverified. Five. The kit's job is to make those five work on a fresh clone with three env vars and a single pnpm dev. The agent's job is to use them well. Why the wiring beats the model A worked example. The bug: "users in Germany see EUR prices but get charged in USD." With no wiring, the agent greps for currency, finds the Stripe call, edits the line, writes a test, says done. Whether it's actually fixed is a coin flip — it has no way to read the live Stripe customer, no way to verify the locale-aware price was created, no way to check the webhook payload. With the payments MCP wired, the agent does this instead: > Look up the German test customer in Stripe and list the prices for that locale. > [tools: stripe.list_customers, stripe.list_prices] > Create a EUR price for the Germany locale if one doesn't exist. > [tools: stripe.create_price] > Read the last 5 webhook events for that customer and confirm currency matches. > [tools: stripe.list_events] > Run the integration test against the test customer and paste the result. > [tools: stripe.create_payment_intent] Same model. Same prompt. Completely different outcome. The agent verifies its own work because it can reach the system under test. The other half: prompts that know the wiring Tools are only useful if the agent knows about them. This is the part most "AI-ready" templates skip — they ship a config file and call it a day. The model discovers the tools, sure, but it doesn't know which tool fits which task, or what the team's conventions are, or what the failure mode looks like. A kit that takes this seriously ships a prompts directory: ai/prompts/ 00-overview.md # what this codebase is, what "done" means 10-database.md # when to query directly vs. write a migration 20-payments.md # which Stripe helpers exist, when to use them 30-deploy.md # the deploy script, the rollback procedure 40-auth.md # how sessions work, the impersonation tool 50-on-call.md # what to do when a user reports X Each prompt names the tools, names the patterns, names the failure modes. The agent reads them once, at session start, and they become the operating manual. The durable layer isn't "avoid AI" — it's "give AI the right context so it does the job." What OTF ships today Every full-stack OTF kit — SaaS Dashboard, Fitness, Booking — lands with that operating manual pre-installed. A fresh clone has a CLAUDE.md, a .cursorrules file, and an ai/prompts/ directory with 20+ tested prompts that tell the agent the codebase's conventions, the patterns to follow, and the failure modes to watch for. When you wire MCP on top — Stripe, Postgres, your deploy provider, your auth — those prompts are what steer the agent toward the right tool at the right moment. The kit isn't pre-wired to a specific SaaS in the sense of shipping a working server — that's your integration, and rightly so. What the kit ships is the context that lets the agent use your integration correctly the first time, and a one-script deploy that wires domain, DNS, TLS, and the mobile build when you're ready to ship. SaaS ships with auth, billing, DB, and Stripe wired in the kit itself; Fitness and Booking extend the same wiring pattern across one codebase that runs iOS, Android, and web. [[CONCEPT: the agent as a brilliant writer in a sealed room — wiring and prompts together open the door]] The durable layer is the wiring The most useful thing you can do for your codebase in 2026 isn't pick the right model. It's make the right things reachable. The model will keep getting better on its own. What won't change is that Stripe still needs a secret, Postgres still needs a URL, your deploy still needs a command, and your agent still needs to be told how your codebase works. The kits that ship those things pre-wired — with prompts that explain them — are the ones where the agent actually ships on day one. The rest of the stack churns. This part doesn't.

1 hour ago

enable AI's Full Potential: Structure Your Codebase for Agent Success

Cursor and Claude Code can take a 200-component design system and ship a working admin page without you writing a line. That's not marketing — I've watched it happen on an OTF SaaS kit. The catch is what the agent can do depends almost entirely on the shape of the repo you hand it. A codebase designed to be read by an agent looks nothing like the 4000-line single file most AI app builders produce. The difference isn't prompt magic. It's five boring structural properties, each of which costs almost nothing to add and roughly doubles what an agent can reliably do. OTF kits are the worked example — they're built this way on purpose — but the pattern works in any repo. 1. Module boundaries come before component count An agent extends a codebase the same way a new hire does: by finding the file it needs without scrolling. A repo where every concern lives in its own folder, with one component per file and a barrel export at the root, gives the agent a map. A repo where everything is in app/page.tsx is a single ball of mud the agent has to reason about whole. The shape that works: src/ components/ Button/ Button.tsx Button.test.tsx index.ts Card/ ... lib/ auth.ts billing.ts db.ts routes/ dashboard.tsx settings.tsx Each folder is a unit. The agent can read Card/Card.tsx, understand the prop shape, write a <Card> somewhere else, and never touch the rest. When a kit ships this way, the agent's mental model matches the file tree. When a sandbox ships a flat file, the agent's only option is to keep regenerating the whole thing. The cost of getting this wrong compounds. Every prompt you write into a flat-file repo has to re-explain the layout. Every prompt you write into a folder-per-concern repo just has to ask. 2. Typed contracts are the spec Props are the API of a component. If the type is ButtonProps with explicit variants, the agent reads the file, sees exactly what variants exist, and picks the right one without guessing. If the type is any, the agent has to read the implementation — and at that point you're back to hand-coding. The really useful move is exporting props alongside the component: // components/Card/Card.tsx export type CardProps = { title: string description?: string footer?: React.ReactNode variant?: 'default' | 'elevated' | 'outlined' } export function Card({ title, description, footer, variant = 'default' }: CardProps) { ... } Now an agent prompt can be "use the Card component with variant='elevated' and a footer" and the agent doesn't have to invent a convention — it imports the type. The same pattern works for server functions, DB queries, and route handlers. Every kit ships exported prop types for this exact reason. 3. Write the conventions down, in a file the agent actually reads This is the single highest-use change. Cursor reads .cursorrules. Claude Code reads CLAUDE.md. Most repos have neither. Both files are loaded into the agent's system context on every run, which means whatever you put there is permanent context the agent never has to rediscover. A working .cursorrules is short. It does three things: // .cursorrules - Use components from @otfdashkit/ui, do not write new ones - Tokens live in @otfdashkit/tokens; never hardcode colors/spacing - Server logic in src/lib/, route handlers in src/routes/ - One component per file; barrel-export from index.ts - DB access via typed queries; schema in src/db/schema.ts Every bullet above is an outcome — what to use, where to put things — and any agent can act on it. A repo with a 30-line conventions file out-performs a repo with 30,000 lines of undocumented code, every time. The mistake to avoid: writing the conventions in a README the agent never reads. The README is for humans, who can skim a 4,000-word doc and pull out the parts they need. An agent won't. It will read the rules file and ignore the rest. 4. Tested example prompts — the part nobody ships A CLAUDE.md tells the agent the rules. A folder of tested prompts tells it what success looks like. The difference is like the difference between a style guide and a tutorial — both are useful, but the tutorial is the one that actually moves you forward. The shape that works: ai/ prompts/ 01-add-a-new-page.md # verified: agent produced working route 02-add-a-billing-plan.md # verified: Stripe integration passed 03-add-a-mobile-screen.md # verified: native build succeeded 04-add-an-api-endpoint.md 05-style-a-form-with-tokens.md ... Each prompt file has three sections: the task in plain English, the files the agent should touch, and the verification step ("does it render?", "does the test pass?", "does pnpm ship succeed?"). Before a kit ships, someone has run every one of these prompts against the kit and confirmed the output is correct. The prompt files are part of the kit the same way source files are. This is the bit the sandbox tools don't have and can't easily produce: a verified example of "here's a thing the agent did correctly on this codebase, so the next prompt has a precedent to follow." Twenty verified prompts is a corpus. The agent reads it the way a new hire reads PRs. 5. Idempotent scripts beat imperative setup An agent can't reliably do a 12-step manual setup. It can reliably run one script. The kits ship pnpm dev, pnpm test, pnpm ship, and pnpm preview:mobile — each one does a complete, deterministic thing. The agent reads package.json, sees the scripts, and uses them. { "scripts": { "dev": "vite", "test": "vitest run", "build": "vite build", "ship": "node ./scripts/ship.mjs", "preview:mobile": "node ./scripts/preview-mobile.mjs" } } pnpm ship wires a custom domain, DNS, and TLS. The agent doesn't need to know how — it just runs the command. Every step that used to be tribal knowledge becomes a script, and every script is a single point of invocation the agent can hit. If you can express setup as a script, an agent can run it. If setup is a Slack thread, an agent cannot. Sandbox output vs. an agent-readable repo [[COMPARE: a sandbox-generated single-file app vs. an OTF kit shipped as a foldered repo with rules and prompts]] Property Sandbox output Agent-readable repo (OTF kit) File layout One 4000-line app.tsx Folder-per-concern, one component each Types Inferred, any, or missing Exported props, full type coverage Conventions None .cursorrules + CLAUDE.md Example prompts None 20+ verified prompts in ai/prompts/ Setup "Click deploy" pnpm ship, pnpm preview:mobile Design system Ad-hoc inline styles Shared tokens across web + native Agent extending it Regenerates from scratch Adds new files in the right places The right column isn't free, but it's not expensive either. A kit is built this way once and reused for every project you start from it. What this gets you I started a SaaS dashboard last week by pasting npx otf-kit@latest saas-dashboard into a terminal. Two minutes later I had a folder with a 200-component design system, a Postgres schema, Stripe wired up, a .cursorrules, and a CLAUDE.md. The agent read the conventions file and used the right components on the first prompt. I asked it to add a billing-plan page; it produced one, the test passed, and the dev server rendered it without me touching the layout. [[CONCEPT: conventions written down, types exported, scripts idempotent — an agent-readable repo is a repo a new hire could also onboard from]] That's the test. If a senior engineer can join your repo on Monday and ship a feature on Friday with nothing but the README, the CLAUDE.md, and the existing code, an AI agent can do the same in an afternoon. If a senior engineer needs a 30-minute walkthrough to find where billing lives, an agent has no chance. The part that doesn't change when the model does Cursor and Claude Code will both look different in six months. The model behind them will be replaced twice over. The five properties above won't change — they're properties of the codebase, not the agent. A repo you build this week stays agent-readable through every model upgrade, because the agent is reading the file tree, the types, the conventions file, and the verified prompts. None of those depend on which model is in the loop. That's the layer the sandbox tools can't ship, because they don't have a repo to ship. They have a generated bundle. The bundle is great for a demo. It stops being great the moment you want to extend it, which is also the moment you want an agent to extend it for you. OTF kits exist for exactly this reason: a repo already shaped the way an agent (and a new hire) can read it, with the conventions, types, scripts, and verified prompts in place from day one. Use Cursor, use Claude Code, use whatever agent ships next — and start from a codebase that's ready for it.

5 hours ago