Hey Devs!
I’m Jesse, solo-building Portal One: an AI Agent Command Center to help you orchestrate, automate, and securely manage your AI agents.
One of the biggest undertakings so far? Building a production-ready Model Context Protocol (MCP) server—the backbone that connects user agents to a growing ecosystem of tools and services.
Let’s just say there were some “battle scars” along the way. Here are three of the most valuable (and painful) lessons that shaped our architecture:
1. OAuth 2.0: No Shortcuts in Security
Early on, I was tempted to use simple API keys or JWTs for agent authorization—until I realized the complexity of permissions, multi-tenancy, and external integrations. Security had to be non-negotiable.
Why OAuth 2.0?
- Industry standard, widely supported
- Granular scopes for fine-grained permissions
- Auditable and future-proof
Oh yeah, and it's also part of the MCP Specification.
Key lesson:
Implementing OAuth correctly is hard. Expect lots of trial and error with flows, token introspection, and permission logic.
2. The Big Pivot: Python → TypeScript
I started with Python for the prototype—it’s fast for AI, but when it came to production, I hit walls:
- Type safety issues slowed refactoring
- Async/concurrency model didn’t fit my needs
- Wanted a unified language for backend and integrations
Switching to TypeScript/Node.js instantly paid off:
- Strong typing = fewer runtime bugs
- First-class async/await model
- Huge ecosystem
More importantly though, the official MCP TypeScript SDK had just added support for the two things I needed: authInfo available in the tool context (use the OAuth token to enable authorization), and the Proxy for using the OAuth authorization server (instead of combining the authorization server with the MCP resource server).
Painful truth:
Rewrites are tough, but sometimes necessary for long-term velocity. However, the second time creating something usually results in a better and more thought out implementation.
3. Zod: Data Validation That Won’t Let You Down
With so many tools and unpredictable agent payloads, validating data was a nightmare—until I discovered Zod.
- Declarative, typesafe schemas
- Automatic TypeScript type inference
- Detailed, developer-friendly error messages
- Baked into MCP TypeScript SDK
Example:
import { z } from 'zod';
const AgentEvent = z.object({
agentId: z.string().uuid(),
tool: z.string(),
payload: z.record(z.unknown()),
timestamp: z.coerce.date(),
});
type AgentEvent = z.infer<typeof AgentEvent>;
// Usage:
const parsed = AgentEvent.parse(incomingEvent);
Tip:
Use Zod schemas everywhere: API endpoints, tool integrations, LLM outputs. It's baked into the MCP TypeScript SDK already so you will be using it whether you like it or not.
The following code snippet is the function we use to authorize the token to allow access to resources in the users workspaces.
// Access to the `authInfo` property injected into the request
// by the MCP SDK middleware enables multi-tenancy and authorization.
export function withWorkspaceAccess<T extends z.ZodTypeAny>(
db: Firestore,
inputSchema: T,
handler: (
args: z.infer<T>,
req: RequestHandlerExtra<ServerRequest, ServerNotification>,
userId: string,
) => Promise<CallToolResult>,
) {
return async (
args: z.infer<T>,
req: RequestHandlerExtra<ServerRequest, ServerNotification>,
) => {
const userId = req.authInfo?.extra?.user_id as string;
if (!userId) throw new Error('No user ID found in token.');
const hasAccess = await checkWorkspaceAccess(db, userId, args.workspace_id);
if (!hasAccess)
throw new Error('You do not have access to this workspace.');
return handler(args, req, userId);
};
}
This short snippet is great at demonstrating each of the "Battle Scars" outlined above. You can check out the GitHub repo as well to see the full example code.
Want More “Battle Scars”?
This is just a taste!
I wrote up a full deep dive—architecture, more code, and the gnarly bits—on the Portal One blog. Check it out!
What’s the hardest lesson you’ve learned building agent backends, APIs, or scalable integrations?
Drop your “battle scars” in the comments—let’s trade notes and help each other out!