Architecting Extensible AI Workflows with the Model Context Protocol

type: "text", text: Error: ${message} }] }; } } );

// Tool 3: Retrieve remote payloads with timeout controls
this.server.tool(
  "fetch_remote_payload",
  "Download text content from an HTTP/HTTPS endpoint. Enforces scheme validation and size caps.",
  {
    endpoint_url: z.string().url().describe("Target HTTP/HTTPS URL"),
    char_limit: z.number().default(4000).describe("Maximum characters to return"),
  },
  async ({ endpoint_url, char_limit }) => {
    try {
      const controller = new AbortController();
      const timeout = setTimeout(() => controller.abort(), 12000);

      const response = await fetch(endpoint_url, {
        signal: controller.signal,
        headers: { "User-Agent": "MCP-Workspace-Server/1.0" },
      });
      clearTimeout(timeout);

      if (!response.ok) {
        return { content: [{ type: "text", text: `Error: HTTP ${response.status} ${response.statusText}` }] };
      }

      const text = await response.text();
      return { content: [{ type: "text", text: text.slice(0, char_limit) }] };
    } catch (err) {
      const message = err instanceof Error ? err.message : "Network request failed";
      return { content: [{ type: "text", text: `Error: ${message}` }] };
    }
  }
);

}

private registerResources(): void { // Resource: Runtime configuration snapshot this.server.resource( "runtime://config", "application/json", async () => ({ contents: [ { uri: "runtime://config", mimeType: "application/json", text: JSON.stringify({ environment: process.env.NODE_ENV || "development", max_concurrent_tools: 3, log_level: "info", }), }, ], }) );

// Resource: Project manifest
this.server.resource(
  "project://manifest",
  "text/markdown",
  async () => {
    try {
      const pkgPath = path.resolve("package.json");
      const data = await fs.readFile(pkgPath, "utf-8");
      return {
        contents: [
          {
            uri: "project://manifest",
            mimeType: "text/markdown",
            text: `# Project Manifest\n\`\`\`json\n${data}\n\`\`\``,
          },
        ],
      };
    } catch {
      return {
        contents: [
          {
            uri: "project://manifest",
            mimeType: "text/markdown",
            text: "# Project Manifest\n\nNo package.json found in working directory.",
          },
        ],
      };
    }
  }
);

}

public async start(): Promise<void> { const transport = new StdioServerTransport(); await this.server.connect(transport); console.error("[MCP] Workspace bridge initialized. Listening on stdio."); } }

// Entry point if (require.main === module) { const bridge = new WorkspaceBridge(); bridge.start().catch((err) => { console.error("[MCP] Fatal startup error:", err); process.exit(1); }); }

### Architecture Decisions & Rationale

1. **Class-Based Encapsulation**: Wrapping the server in a class isolates tool registration, resource mapping, and transport initialization. This prevents global namespace pollution and makes unit testing straightforward.
2. **Zod Schema Validation**: Using `zod` for parameter definitions ensures strict type checking before execution. The LLM receives accurate schema hints, reducing hallucination and malformed calls.
3. **Explicit Error Serialization**: Tools never throw uncaught exceptions. Every failure path returns a structured `content` array with a `text` type. This guarantees the client receives parseable JSON-RPC responses regardless of runtime state.
4. **Stdio Transport Default**: Local AI clients expect stdio for low-latency, secure communication. HTTP transport is reserved for remote or multi-tenant deployments. Starting with stdio eliminates CORS, authentication, and firewall complexity during development.
5. **Resource vs Tool Separation**: Resources are read-only and URI-addressable. Tools are executable and parameterized. Mixing these concepts breaks the MCP semantic contract and confuses client routing logic.

## Pitfall Guide

### 1. Vague Tool Descriptions
**Explanation**: LLMs rely on docstrings to decide which tool to invoke. Generic descriptions like "get data" or "run command" cause incorrect tool selection or parameter hallucination.
**Fix**: Write precise, action-oriented descriptions. Include expected input formats, output structure, and failure conditions. Example: `"Retrieve text content from a local file. Enforces size limits and path validation."`

### 2. Blocking the Stdio Transport
**Explanation**: Long-running synchronous operations freeze the stdio channel. The client times out, and subsequent tool calls queue indefinitely.
**Fix**: Use async/await patterns. Offload heavy computation to worker threads or external queues. Implement explicit timeouts and cancellation tokens for I/O operations.

### 3. Unbounded Resource Consumption
**Explanation**: Reading entire files or fetching unlimited URLs exhausts memory and triggers client-side truncation. LLMs receive partial data, leading to incomplete reasoning.
**Fix**: Enforce byte/character limits at the server level. Stream large payloads in chunks if the client supports it. Always validate input sizes before allocation.

### 4. Relative Path Resolution in Client Configs
**Explanation**: Claude Desktop and Claude Code resolve paths relative to their own launch directories, not your project root. Relative paths in configuration files fail silently.
**Fix**: Always use absolute paths in `claude_desktop_config.json` or `.claude/settings.json`. Resolve paths programmatically during server startup if dynamic.

### 5. Mixing Tool and Resource Responsibilities
**Explanation**: Returning executable logic from a resource URI, or treating a tool as a static data endpoint, violates MCP semantics. Clients route requests differently based on type.
**Fix**: Keep resources strictly read-only and URI-addressable. Keep tools strictly executable and parameterized. Never cross the boundary.

### 6. Inadequate Error Serialization
**Explanation**: Throwing raw JavaScript errors or returning unstructured strings breaks JSON-RPC parsing. The client drops the response and logs a protocol error.
**Fix**: Always return the MCP content schema: `{ content: [{ type: "text", text: "..." }] }`. Wrap all execution in try/catch blocks. Serialize stack traces to stderr, not to the client.

### 7. Skipping Inspector Validation
**Explanation**: Deploying tools without manual verification leads to runtime failures in production. LLMs amplify small schema mismatches into cascading errors.
**Fix**: Run `mcp dev server.js` before deployment. Use the interactive inspector to validate parameter parsing, return types, and error handling. Automate this step in CI pipelines.

## Production Bundle

### Action Checklist
- [ ] Initialize TypeScript project with strict mode and NodeNext module resolution
- [ ] Install `@modelcontextprotocol/sdk` and `zod` for schema validation
- [ ] Implement class-based server architecture to isolate tool/resource registration
- [ ] Define explicit Zod schemas for all tool parameters with descriptive hints
- [ ] Enforce size limits, timeouts, and path validation on every I/O operation
- [ ] Serialize all responses using the MCP content schema; never throw raw exceptions
- [ ] Validate server behavior using `mcp dev` inspector before client deployment
- [ ] Configure absolute paths in client JSON files; verify virtualenv/runtime alignment

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Local development & desktop AI | Stdio transport with FastMCP/SDK | Zero network overhead, secure by default, instant feedback | Minimal (dev time only) |
| Multi-user SaaS or remote agents | HTTP transport with JWT auth | Enables scaling, load balancing, and cross-network access | Moderate (infrastructure + auth layer) |
| High-frequency tool calls | Async execution + connection pooling | Prevents stdio blocking and client timeouts | Low (architectural adjustment) |
| Sensitive data exposure | Resource URIs with read-only access | Prevents accidental mutation; clients cache safely | Low (schema design) |
| Rapid prototyping | Python `mcp` SDK | Faster iteration, less boilerplate | Low (language preference) |

### Configuration Template

**Claude Desktop (macOS)**
Path: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
  "mcpServers": {
    "workspace-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/dist/server.js"]
    }
  }
}

Claude Desktop (Windows) Path: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "workspace-bridge": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\dist\\server.js"]
    }
  }
}

Claude Code (Per-Project) Path: .claude/settings.json

{
  "mcpServers": {
    "workspace-bridge": {
      "command": "node",
      "args": ["./dist/server.js"]
    }
  }
}

CLI Registration (Claude Code)

claude mcp add workspace-bridge node /absolute/path/to/dist/server.js
claude mcp list

Quick Start Guide

1. Initialize: Run npm init -y && npm install @modelcontextprotocol/sdk zod. Configure tsconfig.json for strict NodeNext compilation.
2. Build: Create src/server.ts using the class-based architecture above. Compile with npx tsc.
3. Validate: Execute mcp dev dist/server.js. Use the browser inspector to call read_workspace_artifact and scan_directory_tree. Verify JSON-RPC responses.
4. Deploy: Add absolute path to claude_desktop_config.json or run claude mcp add. Restart the client. Confirm the hammer icon appears in the interface.
5. Iterate: Add new tools by extending the registerTools() method. Update Zod schemas. Re-run the inspector. Commit changes.

The Model Context Protocol transforms AI tooling from a fragmented integration challenge into a standardized infrastructure layer. By decoupling transport, enforcing strict schemas, and isolating business logic, you build systems that scale across clients, survive model updates, and reduce maintenance overhead. Treat your MCP server as a contract, not a script. Validate aggressively, serialize predictably, and let the protocol handle the rest.