Claude MCP Hybrid Architecture — Design Patterns for Combining Deterministic Tools with AI Reasoning

// mcp-server/tools/database-query.ts
// Database query tool — a deterministic operation
import { z } from "zod";
 
const QueryParamsSchema = z.object({
  table: z.string().describe("Target table name"),
  filters: z.record(z.string()).describe("Filter conditions (key=column, value=condition)"),
  limit: z.number().default(10).describe("Maximum number of records to return"),
});
 
export const databaseQueryTool = {
  name: "query_database",
  description: "Retrieve records from a table matching the specified filter conditions",
  inputSchema: QueryParamsSchema,
 
  async execute(params: z.infer<typeof QueryParamsSchema>) {
    // Execute query deterministically with validated parameters
    const { table, filters, limit } = params;
 
    const whereClause = Object.entries(filters)
      .map(([key, value]) => `${key} = '${value}'`)
      .join(" AND ");
 
    const query = `SELECT * FROM ${table} WHERE ${whereClause} LIMIT ${limit}`;
 
    // Results are deterministic for the same input and data state
    const results = await db.execute(query);
    return { success: true, data: results, query };
  },
};

// orchestrator/hybrid-agent.ts
// Hybrid agent using Claude as the orchestrator
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
async function runHybridAgent(userMessage: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    system: `You are a data analysis assistant.
Analyze the user's request and call the appropriate tools.
 
Key design principles:
1. Always use tools for calculations and data retrieval (never compute yourself)
2. Trust tool results as ground truth (never "imagine" results)
3. When multiple tools are needed, determine execution order based on dependencies
4. If an error occurs, consider alternatives before reporting to the user`,
    tools: mcpTools, // Tool definitions fetched from MCP server
    messages: [{ role: "user", content: userMessage }],
  });
 
  return response;
}

// orchestrator/result-synthesizer.ts
// Logic for synthesizing tool execution results
async function synthesizeResults(
  toolResults: ToolResult[],
  originalQuery: string
) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 2048,
    messages: [
      {
        role: "user",
        content: `Synthesize the following tool results to answer the user's question.
 
User question: ${originalQuery}
 
Tool execution results:
${toolResults
  .map(
    (r, i) =>
      `[Tool ${i + 1}: ${r.toolName}]\n${JSON.stringify(r.output, null, 2)}`
  )
  .join("\n\n")}
 
Response rules:
- Use numerical data exactly as returned by tools
- Clearly state when you are inferring or extrapolating
- Report any contradictions between tool results`,
      },
    ],
  });
 
  return response;
}

// patterns/plan-execute-verify.ts
// Plan-Execute-Verify loop pattern
 
const systemPrompt = `You are a task execution agent.
Follow these three steps for every request:
 
Step 1 - Plan: Analyze the request and output an execution plan
  as a JSON array of tool calls.
Step 2 - Execute: Call tools in the planned sequence.
Step 3 - Verify: Review all results. If they match expectations,
  provide the final answer. If not, revise the plan and retry.`;
 
async function planExecuteVerify(userRequest: string) {
  let attempts = 0;
  const maxAttempts = 3;
 
  while (attempts < maxAttempts) {
    // Step 1: Claude creates a plan (probabilistic)
    const plan = await generatePlan(userRequest);
 
    // Step 2: Execute the plan via tools (deterministic)
    const results = await executePlan(plan);
 
    // Step 3: Claude verifies results (probabilistic)
    const verification = await verifyResults(results, userRequest);
 
    if (verification.isSuccess) {
      return verification.finalResponse;
    }
 
    // Verification failed — refine and retry
    userRequest = `Previous results: ${JSON.stringify(results)}
Feedback: ${verification.feedback}
Original request: ${userRequest}`;
    attempts++;
  }
 
  return "Maximum retry attempts reached. Please review manually.";
}

// patterns/tool-narrowing.ts
// Progressive tool narrowing pattern
 
const toolCategories = {
  database: ["query_database", "insert_record", "update_record"],
  file: ["read_file", "write_file", "list_directory"],
  api: ["http_get", "http_post", "graphql_query"],
  calculation: ["statistics", "aggregate", "transform"],
};
 
async function narrowAndExecute(userMessage: string) {
  // Phase 1: Category classification (minimal tokens)
  const categoryResponse = await client.messages.create({
    model: "claude-haiku-4-5", // Lightweight model for classification
    max_tokens: 100,
    messages: [
      {
        role: "user",
        content: `Select the tool category needed for this request.
Categories: database, file, api, calculation
Request: ${userMessage}
Category name only:`,
      },
    ],
  });
 
  const category = categoryResponse.content[0].text.trim();
 
  // Phase 2: Execute with narrowed tool set (saves tokens)
  const relevantTools = toolCategories[category] || [];
  const fullTools = await getMCPTools(relevantTools);
 
  return client.messages.create({
    model: "claude-sonnet-4-6", // Full model for execution
    max_tokens: 4096,
    tools: fullTools,
    messages: [{ role: "user", content: userMessage }],
  });
}

// patterns/deterministic-guardrails.ts
// Deterministic guardrails pattern
 
interface GuardrailCheck {
  name: string;
  check: (toolCall: ToolCall) => { allowed: boolean; reason?: string };
}
 
const guardrails: GuardrailCheck[] = [
  {
    name: "SQL_INJECTION_CHECK",
    check: (call) => {
      if (call.name === "query_database") {
        const hasInjection = /;\s*(DROP|DELETE|UPDATE)\s/i.test(
          JSON.stringify(call.input)
        );
        return hasInjection
          ? { allowed: false, reason: "Suspected SQL injection" }
          : { allowed: true };
      }
      return { allowed: true };
    },
  },
  {
    name: "RATE_LIMIT_CHECK",
    check: (call) => {
      const count = getRecentCallCount(call.name, 60); // Last 60 seconds
      return count > 10
        ? { allowed: false, reason: `Rate limit exceeded: ${count}/10 per min` }
        : { allowed: true };
    },
  },
];
 
// Always run guardrails before executing any tool
async function executeWithGuardrails(toolCall: ToolCall) {
  for (const guardrail of guardrails) {
    const result = guardrail.check(toolCall);
    if (!result.allowed) {
      return {
        success: false,
        error: `Guardrail [${guardrail.name}]: ${result.reason}`,
      };
    }
  }
  // All checks passed — execute the tool
  return await executeTool(toolCall);
}

// example/sales-analysis-agent.ts
// Sales analysis hybrid agent implementation
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
// Deterministic tool definitions
const salesTools = [
  {
    name: "get_sales_data",
    description: "Retrieve sales data for a specified date range",
    input_schema: {
      type: "object",
      properties: {
        start_date: { type: "string", description: "Start date (YYYY-MM-DD)" },
        end_date: { type: "string", description: "End date (YYYY-MM-DD)" },
        product_category: {
          type: "string",
          description: "Product category (omit for all categories)",
        },
      },
      required: ["start_date", "end_date"],
    },
  },
  {
    name: "calculate_statistics",
    description:
      "Calculate statistical values (mean, median, standard deviation) for a number array",
    input_schema: {
      type: "object",
      properties: {
        values: {
          type: "array",
          items: { type: "number" },
          description: "Array of numbers to analyze",
        },
      },
      required: ["values"],
    },
  },
];
 
async function analyzeSales(question: string) {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: question },
  ];
 
  // Agent loop: keep running until tool calls are complete
  let continueLoop = true;
  while (continueLoop) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 4096,
      system: `You are a sales analysis expert.
Always use tools to retrieve and calculate data for the user's questions.
Never estimate numbers yourself — rely solely on tool results as evidence.`,
      tools: salesTools,
      messages,
    });
 
    if (response.stop_reason === "tool_use") {
      // Execute tool calls (deterministic processing)
      const toolResults = [];
      for (const block of response.content) {
        if (block.type === "tool_use") {
          const result = await executeWithGuardrails(block);
          toolResults.push({
            type: "tool_result",
            tool_use_id: block.id,
            content: JSON.stringify(result),
          });
        }
      }
      // Add to conversation history for next iteration
      messages.push({ role: "assistant", content: response.content });
      messages.push({ role: "user", content: toolResults });
    } else {
      // Final answer received
      continueLoop = false;
      return response.content;
    }
  }
}
 
// Usage example
// Expected behavior:
// 1. Claude calls get_sales_data (deterministic)
// 2. Claude calls calculate_statistics on the retrieved data (deterministic)
// 3. Claude interprets the statistics and generates a report (probabilistic)
const report = await analyzeSales(
  "Compare last month's sales with this month and analyze the trend"
);
console.log(report);