feat(mcp): add cloud runtime preflight tool

Expose check_cloud_agent_runtime so lead agents can validate runtime routing and AWS AgentCore reachability before calling spawn_cloud_agent.

Author: vamgan

README.md

@@ -44,11 +44,12 @@ Running this inline consumes context, blocks the lead-agent session, and loses c
 
 ## What it does
 
-A single MCP server exposes nine tools to your assistant:
+A single MCP server exposes ten tools to your assistant:
 
 | Tool | What it does |
 | --- | --- |
 | `spawn_cloud_agent` | The shortcut. One `instruction`, defaults from a runtime profile, returns a durable `taskId` and optional `cloudAgent` metadata. |
+| `check_cloud_agent_runtime` | Preflight a configured runtime before spawning. For AWS AgentCore, it can verify credentials and runtime/control-plane reachability. |
 | `dispatch_task` | The escape hatch. Full control over provider, capability, backend, target, and input. |
 | `get_task_status` | Current status for a dispatched task. |
 | `get_task_logs` | Paginated logs, cursor-based. |
@@ -61,6 +62,9 @@ A single MCP server exposes nine tools to your assistant:
 The model side looks like this:
 
 ```ts
+check_cloud_agent_runtime({ runtime: "research-agent" })
+// → { ok: true, checks: [...] }
+
 spawn_cloud_agent({ instruction: "Audit our S3 buckets for public read and report findings." })
 // → { taskId: "task_...", status: "queued", cloudAgent: { ... } }
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dispatch/mcp-server",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Provider-neutral MCP server for AgentDispatch.",
   "type": "module",
   "license": "Apache-2.0",

package.json

@@ -1,9 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { AgentDispatchError, type DispatchRequest, type RuntimeProfile, type RuntimeService } from "@agent-dispatch/core";
+import { checkAwsAgentCoreLivePreflight, type AwsAgentCoreLivePreflightCheck, type AwsAgentCoreLivePreflightInput } from "@agent-dispatch/adapter-aws-agentcore";
 import packageJson from "../package.json" with { type: "json" };
 import { mcpToolSchemas } from "./schemas.js";
 
-export function createAgentDispatchMcpServer(runtime: RuntimeService): McpServer {
+export interface AgentDispatchMcpServerOptions {
+  awsAgentCoreLivePreflight?: (input: AwsAgentCoreLivePreflightInput) => Promise<AwsAgentCoreLivePreflightCheck[]>;
+}
+
+export function createAgentDispatchMcpServer(runtime: RuntimeService, options: AgentDispatchMcpServerOptions = {}): McpServer {
   const server = new McpServer({ name: "agentdispatch", version: packageJson.version });
 
   server.tool("list_providers", mcpToolSchemas.list_providers.shape, async () => jsonContent(runtime.listProviders()));
@@ -14,6 +19,10 @@ export function createAgentDispatchMcpServer(runtime: RuntimeService): McpServer
 
   server.tool("list_account_profiles", mcpToolSchemas.list_account_profiles.shape, async () => jsonContent(runtime.listAccountProfiles()));
 
+  server.tool("check_cloud_agent_runtime", mcpToolSchemas.check_cloud_agent_runtime.shape, async (input) => {
+    return jsonContent(await createCloudAgentRuntimeCheck(runtime, input, options));
+  });
+
   server.tool("spawn_cloud_agent", mcpToolSchemas.spawn_cloud_agent.shape, async (input) => {
     const clarification = createSpawnClarification(runtime, input);
     if (clarification) return jsonContent(clarification);
@@ -56,6 +65,113 @@ export function createAgentDispatchMcpServer(runtime: RuntimeService): McpServer
 export * from "./bootstrap.js";
 export * from "./schemas.js";
 
+async function createCloudAgentRuntimeCheck(runtime: RuntimeService, input: {
+  runtime?: string;
+  provider?: string;
+  account_profile?: string;
+  live?: boolean;
+  runtimeArn?: string;
+  runtime_arn?: string;
+  target?: { mode?: string; protocol?: string; details?: Record<string, unknown> };
+}, options: AgentDispatchMcpServerOptions) {
+  const checks: Array<{ name: string; status: "pass" | "warn" | "fail"; message: string }> = [];
+  const defaults = runtime.getDefaults();
+  const profile = selectRuntimeProfileForCheck(runtime, input.runtime, input.provider);
+  if (!profile) {
+    checks.push({
+      name: "runtime",
+      status: "fail",
+      message: input.runtime
+        ? `Runtime profile ${input.runtime} is not configured.`
+        : "No default runtime profile is configured."
+    });
+    return cloudAgentRuntimeCheckResult({ checks });
+  }
+
+  const backend = runtime.getBackend(profile.backend);
+  const accountName = input.account_profile ?? profile.account ?? defaults.accountProfile;
+  const account = runtime.listAccountProfiles().find((candidate) => candidate.name === accountName);
+  const targetMode = input.target?.mode ?? profile.target?.mode ?? defaults.targetMode ?? "session";
+  checks.push({
+    name: "runtime",
+    status: "pass",
+    message: `Runtime ${profile.name} routes ${profile.provider}/${profile.capability}/${targetMode} through ${profile.backend}.`
+  });
+
+  if (!backend) {
+    checks.push({
+      name: "backend",
+      status: "fail",
+      message: `Runtime ${profile.name} references missing backend ${profile.backend}.`
+    });
+    return cloudAgentRuntimeCheckResult({ profile, account, backend, targetMode, checks });
+  }
+  checks.push({
+    name: "backend",
+    status: "pass",
+    message: `Backend ${profile.backend} uses adapter ${backend.adapter}.`
+  });
+
+  if (!account) {
+    checks.push({
+      name: "account_profile",
+      status: "fail",
+      message: accountName ? `Account profile ${accountName} is not configured.` : "No account profile is configured for this runtime."
+    });
+    return cloudAgentRuntimeCheckResult({ profile, account, backend, targetMode, checks });
+  }
+  checks.push({
+    name: "account_profile",
+    status: "pass",
+    message: `Account profile ${account.name} uses provider ${account.provider}.`
+  });
+
+  if (input.live !== false && account.provider === "aws" && backend.adapter === "aws-agentcore") {
+    const targetDetails = mergeRecords(profile.target?.details, spawnTargetDetails(input), input.target?.details) ?? {};
+    const preflight = options.awsAgentCoreLivePreflight ?? checkAwsAgentCoreLivePreflight;
+    checks.push(...await preflight({
+      runtimeName: profile.name,
+      region: account.region ?? String(backend.details?.region ?? process.env.AWS_REGION ?? "us-east-1"),
+      mode: targetMode,
+      runtimeArn: stringValue(targetDetails.runtimeArn) ?? stringValue(backend.details?.runtimeArn) ?? process.env.AGENTDISPATCH_AGENTCORE_RUNTIME_ARN
+    }));
+  } else if (input.live !== false) {
+    checks.push({
+      name: "live",
+      status: "warn",
+      message: `Live preflight is not implemented for ${account.provider}/${backend.adapter}.`
+    });
+  }
+
+  return cloudAgentRuntimeCheckResult({ profile, account, backend, targetMode, checks });
+}
+
+function cloudAgentRuntimeCheckResult(input: {
+  profile?: RuntimeProfile;
+  account?: { name: string; provider: string; region?: string; credentialSource: string };
+  backend?: { adapter: string };
+  targetMode?: string;
+  checks: Array<{ name: string; status: "pass" | "warn" | "fail"; message: string }>;
+}) {
+  return {
+    ok: input.checks.every((check) => check.status !== "fail"),
+    runtime: input.profile?.name,
+    provider: input.account?.provider ?? input.profile?.provider,
+    account_profile: input.account?.name ?? input.profile?.account,
+    backend: input.profile?.backend,
+    adapter: input.backend?.adapter,
+    target_mode: input.targetMode,
+    checks: input.checks
+  };
+}
+
+function selectRuntimeProfileForCheck(runtime: RuntimeService, runtimeName?: string, provider?: string): RuntimeProfile | undefined {
+  if (runtimeName) return runtime.getRuntimeProfile(runtimeName);
+  const defaultProfile = runtime.getDefaultRuntimeProfile();
+  if (defaultProfile && (!provider || defaultProfile.provider === provider)) return defaultProfile;
+  return runtime.listRuntimeProfiles().find((profile) => !provider || profile.provider === provider);
+}
+
 function createSpawnCloudAgentRequest(runtime: RuntimeService, input: {
   instruction?: string;
   runtime?: string;
@@ -293,6 +409,10 @@ function stringRecord(key: string, value: unknown): Record<string, unknown> | un
   return typeof value === "string" && value.length > 0 ? { [key]: value } : undefined;
 }
 
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
 function recordRecord(key: string, value: unknown): Record<string, unknown> | undefined {
   return value && typeof value === "object" && !Array.isArray(value) ? { [key]: value } : undefined;
 }

src/index.ts

@@ -45,6 +45,20 @@ export const spawnCloudAgentInputSchema = z.object({
   metadata: z.record(z.unknown()).optional()
 });
 
+export const checkCloudAgentRuntimeInputSchema = z.object({
+  runtime: z.string().optional(),
+  provider: z.string().optional(),
+  account_profile: z.string().optional(),
+  live: z.boolean().optional(),
+  runtimeArn: z.string().optional(),
+  runtime_arn: z.string().optional(),
+  target: z.object({
+    mode: z.string().optional(),
+    protocol: z.string().optional(),
+    details: z.record(z.unknown()).optional()
+  }).optional()
+});
+
 export const taskIdInputSchema = z.object({
   task_id: z.string()
 });
@@ -59,6 +73,7 @@ export const mcpToolSchemas = {
   list_providers: z.object({}),
   list_capabilities: listCapabilitiesInputSchema,
   list_account_profiles: z.object({}),
+  check_cloud_agent_runtime: checkCloudAgentRuntimeInputSchema,
   spawn_cloud_agent: spawnCloudAgentInputSchema,
   dispatch_task: dispatchTaskInputSchema,
   get_task_status: taskIdInputSchema,

src/schemas.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { afterEach, describe, expect, it } from "vitest";
 import { RuntimeService, type BackendAdapter, type DispatchRequest, type RuntimeEvent, type RuntimeRecord, type TaskStore } from "@agent-dispatch/core";
-import { createAgentDispatchMcpServer, createRuntimeServiceFromConfig } from "../src/index.js";
+import { createAgentDispatchMcpServer, createRuntimeServiceFromConfig, type AgentDispatchMcpServerOptions } from "../src/index.js";
 
 const tempDirs: string[] = [];
 
@@ -133,9 +133,9 @@ function createRuntime(adapter = mockAdapter([{ taskId: "ignored", type: "task.l
   });
 }
 
-async function createClient(runtime = createRuntime()) {
+async function createClient(runtime = createRuntime(), options?: AgentDispatchMcpServerOptions) {
   const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-  const server = createAgentDispatchMcpServer(runtime);
+  const server = createAgentDispatchMcpServer(runtime, options);
   const client = new Client({ name: "agentdispatch-test", version: "0.1.0" });
   await server.connect(serverTransport);
   await client.connect(clientTransport);
@@ -236,6 +236,73 @@ describe("MCP tool invocation", () => {
     }
   });
 
+  it("checks cloud runtime readiness through the agent-facing MCP tool", async () => {
+    const runtime = new RuntimeService({
+      config: {
+        accounts: { "dev-aws": { provider: "aws", region: "us-west-2", credentialSource: "aws-sdk-default" } },
+        backends: {
+          "aws-agentcore": {
+            provider: "aws",
+            capability: "agent-runtime",
+            adapter: "aws-agentcore",
+            account: "dev-aws"
+          }
+        },
+        runtimes: {
+          "research-agent": {
+            provider: "aws",
+            account: "dev-aws",
+            capability: "agent-runtime",
+            backend: "aws-agentcore",
+            protocol: "a2a",
+            target: {
+              mode: "session",
+              protocol: "a2a",
+              details: { runtimeArn: "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/11111111-1111-1111-1111-111111111111:1" }
+            }
+          }
+        },
+        defaults: { runtime: "research-agent" }
+      },
+      store: new MemoryStore(),
+      adapters: [mockAdapter([], "aws-agentcore")]
+    });
+    let liveInput: unknown;
+    const { client, server } = await createClient(runtime, {
+      awsAgentCoreLivePreflight: async (input) => {
+        liveInput = input;
+        return [{
+          name: `aws.${input.runtimeName}.runtime`,
+          status: "pass",
+          message: `runtime ${input.runtimeArn} reachable`
+        }];
+      }
+    });
+    try {
+      const response = await callJson(client, "check_cloud_agent_runtime", { runtime: "research-agent" });
+      expect(response).toMatchObject({
+        ok: true,
+        runtime: "research-agent",
+        provider: "aws",
+        account_profile: "dev-aws",
+        adapter: "aws-agentcore",
+        checks: expect.arrayContaining([
+          expect.objectContaining({ name: "runtime", status: "pass" }),
+          expect.objectContaining({ name: "aws.research-agent.runtime", status: "pass" })
+        ])
+      });
+      expect(liveInput).toMatchObject({
+        runtimeName: "research-agent",
+        region: "us-west-2",
+        mode: "session",
+        runtimeArn: "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/11111111-1111-1111-1111-111111111111:1"
+      });
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+
   it("surfaces unsupported provider errors to MCP clients", async () => {
     const { client, server } = await createClient();
     try {

test/e2e.test.ts

@@ -23,6 +23,7 @@ describe("MCP schemas", () => {
   it("exports stable MCP tool schemas", () => {
     expect(Object.keys(mcpToolSchemas).sort()).toEqual([
       "cancel_task",
+      "check_cloud_agent_runtime",
       "dispatch_task",
       "get_task_logs",
       "get_task_result",
@@ -34,6 +35,18 @@ describe("MCP schemas", () => {
     ]);
   });
 
+  it("accepts cloud runtime preflight input", () => {
+    expect(mcpToolSchemas.check_cloud_agent_runtime.parse({
+      runtime: "research-agent",
+      live: true,
+      runtimeArn: "arn:aws:bedrock-agentcore:us-west-2:123456789012:agent/11111111-1111-1111-1111-111111111111:1"
+    })).toMatchObject({
+      runtime: "research-agent",
+      live: true,
+      runtimeArn: expect.stringContaining("agent/11111111")
+    });
+  });
+
   it("keeps spawn_cloud_agent simple for agents", () => {
     const parsed = spawnCloudAgentInputSchema.parse({
       runtime: "research-agent",