improvement(mcp): advertise server metadata, output schemas, and clearer tool docs (#9037)

Author: waleedlatif1

apps/sim/lib/api/contracts/types.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod'
 
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
 
 export type ApiSchema = z.ZodType
 

apps/sim/lib/api/mcp/catalog.ts

@@ -1,6 +1,6 @@
 import { omit, toRecord } from '@sim/utils/object'
 import { z } from 'zod'
-import type { ApiSchema, HttpMethod } from '@/lib/api/contracts/types'
+import type { ApiSchema } from '@/lib/api/contracts/types'
 import { V2_MCP_OPERATIONS, type V2McpOperationName } from '@/lib/api/mcp/generated/v2-operations'
 import type { V2McpOperation } from '@/lib/api/mcp/types'
 import { v2RouteOperation } from '@/lib/api/server/routes/v2-json-route'
@@ -20,30 +20,59 @@ export const TOOL_NAMES = { read: 'call_read_operation', write: 'call_write_oper
 type ToolKind = keyof typeof TOOL_NAMES
 
 const REQUEST_SLOTS = ['params', 'query', 'body', 'headers'] as const
-type RequestSlot = (typeof REQUEST_SLOTS)[number]
-type JsonSchema = Record<string, unknown>
 
-/** One catalog row: enough to choose an operation, not to call it. */
-interface McpOperationEntry {
-  operation: V2McpOperationName
-  method: HttpMethod
-  path: string
-  domain: string
-  summary: string
-  /** The tool that runs it: the read tool only for operations that need nothing beyond read access. */
-  /** Refuses workspace API keys; call it with a personal key or an OAuth connection. */
-  personalCredentialOnly?: true
-}
+const operationSummarySchema = z.object({
+  operation: z
+    .string()
+    .describe('Operation name to pass to describe_operation and the call tools.'),
+  method: z
+    .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])
+    .describe('HTTP method of the Sim API route.'),
+  path: z.string().describe('Sim API route path; bracketed segments are path parameters.'),
+  domain: z.string().describe('API area, usable as the search_operations domain.'),
+  summary: z.string(),
+  tool: z
+    .enum([TOOL_NAMES.read, TOOL_NAMES.write])
+    .describe(
+      'The tool that runs the operation: the read tool only for operations that need nothing beyond read access.'
+    ),
+  personalCredentialOnly: z
+    .literal(true)
+    .optional()
+    .describe(
+      'Present when the operation refuses workspace API keys; call it with a personal API key or an OAuth connection.'
+    ),
+})
 
-interface McpOperationSummary extends McpOperationEntry {
-  /** The tool that runs it: the read tool only for operations that need nothing beyond read access. */
-  tool: (typeof TOOL_NAMES)[ToolKind]
-}
+const jsonSchema = z.record(z.string(), z.unknown())
+
+export const searchOperationsOutput = z.object({
+  total: z.number().describe('How many operations match, which can exceed those returned.'),
+  operations: z.array(operationSummarySchema).describe('Matching operations, best match first.'),
+})
 
-/** Everything needed to call one operation: its documentation plus the JSON Schema of each request slot. */
-interface McpOperationDescription extends McpOperationSummary {
-  description?: string
-  input: Partial<Record<RequestSlot, JsonSchema>>
+/** What describe_operation returns: everything needed to call one operation. */
+export const describeOperationOutput = operationSummarySchema.extend({
+  description: z.string().optional().describe('Longer documentation, when the operation has it.'),
+  input: z
+    .object({
+      params: jsonSchema.optional(),
+      query: jsonSchema.optional(),
+      body: jsonSchema.optional(),
+      headers: jsonSchema.optional(),
+    })
+    .describe(
+      'JSON Schema of each request part the operation takes; an absent part takes no input.'
+    ),
+})
+
+type McpOperationSummary = z.infer<typeof operationSummarySchema>
+type McpOperationDescription = z.infer<typeof describeOperationOutput>
+type JsonSchema = z.infer<typeof jsonSchema>
+
+/** One catalog row: enough to choose an operation, not to call it. */
+type McpOperationEntry = Omit<McpOperationSummary, 'operation' | 'tool'> & {
+  operation: V2McpOperationName
 }
 
 const OPERATION_NAMES = Object.keys(V2_MCP_OPERATIONS) as V2McpOperationName[]
@@ -156,7 +185,7 @@ export async function searchOperations(options: {
   query?: string
   domain?: string
   limit: number
-}): Promise<{ total: number; operations: McpOperationSummary[] }> {
+}): Promise<z.infer<typeof searchOperationsOutput>> {
   const ranked = rankOperations(options.query, options.domain)
   return {
     total: ranked.length,

apps/sim/lib/api/mcp/server.ts

@@ -1,23 +1,30 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import { createLogger } from '@sim/logger'
+import { SIM_DOCS_URL } from '@sim/utils/site'
 import { z } from 'zod'
 import {
   describeOperation,
+  describeOperationOutput,
   OPERATION_DOMAINS,
   resolveOperation,
   searchOperations,
+  searchOperationsOutput,
   TOOL_NAMES,
 } from '@/lib/api/mcp/catalog'
 import {
   dispatchMcpOperation,
   type McpDispatchContext,
   type McpOperationCall,
 } from '@/lib/api/mcp/dispatch'
-import { jsonToolResult, toolError } from '@/lib/mcp/tool-result'
+import { getBaseUrl } from '@/lib/core/utils/urls'
+import { structuredToolResult, toolError } from '@/lib/mcp/tool-result'
 
 const logger = createLogger('SimMcpServer')
 
+const DESCRIPTION =
+  'Lets an agent work in Sim, the AI workspace for building, deploying, and managing AI agents: search the Sim API, then read or change workspaces, workflows and their runs, tables, knowledge bases, files, logs, credentials, and deployments.'
+
 const INSTRUCTIONS = `Sim is the AI workspace where teams build, deploy, and manage AI agents. This server exposes the full Sim API: workspaces, workflows and their runs, tables, knowledge bases, files, logs, credentials, deployments, and more.
 
 1. Find an operation with search_operations (keywords, optionally a domain).
@@ -43,8 +50,21 @@ const searchInput = z
       .describe(
         'Keywords matched against operation names, summaries, and paths, e.g. "table rows".'
       ),
-    domain: z.enum(OPERATION_DOMAINS).optional().describe('Only operations in this API area.'),
-    limit: z.number().int().min(1).max(100).default(25),
+    domain: z
+      .enum(OPERATION_DOMAINS)
+      .optional()
+      .describe(
+        'API area to search or list, such as tables, workflows, or knowledge. Omit to search every area.'
+      ),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .default(25)
+      .describe(
+        'How many matching operations to return, best match first. When total in the result is larger, narrow the query or domain.'
+      ),
   })
   .strict()
 
@@ -57,20 +77,28 @@ const callInput = z
     params: z
       .record(z.string(), z.string())
       .optional()
-      .describe('Path parameters by name, e.g. { "tableId": "..." }.'),
+      .describe(
+        'Values for the bracketed segments of the operation’s path, by name, e.g. { "tableId": "..." }. IDs come from list operations such as listTables.'
+      ),
     query: z
       .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
       .optional()
-      .describe('Query-string parameters by name.'),
+      .describe(
+        'Query-string values by name, as the query schema from describe_operation lists them, e.g. { "limit": 50 } or the cursor from the previous page.'
+      ),
     headers: z
       .record(z.string(), z.string())
       .optional()
-      .describe('Request headers the operation declares, such as upload-token.'),
+      .describe(
+        'Headers the operation’s describe_operation schema lists, such as upload-token. Sim sets authentication and content headers itself.'
+      ),
     body: z
       .record(z.string(), z.unknown())
       .meta({ additionalProperties: true })
       .optional()
-      .describe('JSON request body, as describe_operation specifies.'),
+      .describe(
+        'JSON request body matching the body schema from describe_operation. Omit it when the operation takes no body.'
+      ),
   })
   .strict()
 
@@ -84,7 +112,29 @@ const callInput = z
  * tools so a client can approve reads once and still confirm every change.
  */
 export function createSimMcpServer(context: Omit<McpDispatchContext, 'signal'>): McpServer {
-  const server = new McpServer({ name: 'Sim', version: '1.0.0' }, { instructions: INSTRUCTIONS })
+  const baseUrl = getBaseUrl()
+  const server = new McpServer(
+    {
+      name: 'Sim',
+      title: 'Sim',
+      version: '1.0.0',
+      description: DESCRIPTION,
+      websiteUrl: `${SIM_DOCS_URL}/mcp/overview`,
+      icons: [
+        {
+          src: `${baseUrl}/brandbook/icon/green.svg`,
+          mimeType: 'image/svg+xml',
+          sizes: ['any'],
+        },
+        {
+          src: `${baseUrl}/favicon/android-chrome-512x512.png`,
+          mimeType: 'image/png',
+          sizes: ['512x512'],
+        },
+      ],
+    },
+    { instructions: INSTRUCTIONS }
+  )
 
   async function call(
     tool: 'read' | 'write',
@@ -111,8 +161,9 @@ export function createSimMcpServer(context: Omit<McpDispatchContext, 'signal'>):
     {
       title: 'Search operations',
       description:
-        'Find Sim API operations by keyword or domain. Returns each operation’s name, HTTP method, path, summary, and the tool that runs it. Call without a query to list a domain.',
+        'Find Sim API operations by keyword or domain. Returns how many match and, best match first, each operation’s name, HTTP method, path, summary, and the tool that runs it. Call without a query to list a domain.',
       inputSchema: searchInput,
+      outputSchema: searchOperationsOutput,
       annotations: {
         title: 'Search operations',
         readOnlyHint: true,
@@ -121,16 +172,17 @@ export function createSimMcpServer(context: Omit<McpDispatchContext, 'signal'>):
         openWorldHint: false,
       },
     },
-    async (input) => jsonToolResult(await searchOperations(input))
+    async (input) => structuredToolResult(await searchOperations(input))
   )
 
   server.registerTool(
     'describe_operation',
     {
       title: 'Describe operation',
       description:
-        'Get the JSON Schema of an operation’s path parameters, query, body, and headers. Read it before calling an operation for the first time.',
+        'Get what is needed to call one operation: its HTTP method, path, summary, longer description when it has one, the tool that runs it, whether it refuses workspace API keys, and the JSON Schema of its path parameters, query, body, and headers. Read it before calling an operation for the first time.',
       inputSchema: describeInput,
+      outputSchema: describeOperationOutput,
       annotations: {
         title: 'Describe operation',
         readOnlyHint: true,
@@ -143,7 +195,7 @@ export function createSimMcpServer(context: Omit<McpDispatchContext, 'signal'>):
       const resolved = await resolveOperation(operation, 'any')
       return 'error' in resolved
         ? toolError(resolved.error)
-        : jsonToolResult(await describeOperation(resolved.operation))
+        : structuredToolResult(await describeOperation(resolved.operation))
     }
   )
 
@@ -168,12 +220,12 @@ export function createSimMcpServer(context: Omit<McpDispatchContext, 'signal'>):
   server.registerTool(
     TOOL_NAMES.write,
     {
-      title: 'Change Sim',
+      title: 'Write to Sim',
       description:
-        'Run a Sim API operation that creates, changes, runs, or deletes something, such as createTable, executeWorkflow, or deleteFile.',
+        'Run a Sim API operation that needs write access: one that creates, changes, runs, or deletes something, or reaches out to another service, such as createTable, executeWorkflow, or deleteFile. Changes apply immediately, with no preview or undo. A workflow run executes its blocks, which can call external services and use credits, so confirm deletions and runs with the user first.',
       inputSchema: callInput,
       annotations: {
-        title: 'Change Sim',
+        title: 'Write to Sim',
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,

apps/sim/lib/mcp/tool-result.ts

@@ -5,7 +5,7 @@ export function toolError(message: string): CallToolResult {
   return { isError: true, content: [{ type: 'text', text: message }] }
 }
 
-/** A tool result carrying a JSON value as text. */
-export function jsonToolResult(value: unknown): CallToolResult {
-  return { content: [{ type: 'text', text: JSON.stringify(value) }] }
+/** A JSON object as text and as `structuredContent`, for a tool that declares an output schema. */
+export function structuredToolResult(value: Record<string, unknown>): CallToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(value) }], structuredContent: value }
 }