feat(mcp): add initial server instructions

Adds generated MCP server instructions, to help agents get easy tasks on the first try.

Author: stainless-app[bot]

packages/mcp-server/src/http.ts

@@ -9,20 +9,20 @@ import { McpOptions } from './options';
 import { ClientOptions, initMcpServer, newMcpServer } from './server';
 import { parseAuthHeaders } from './headers';
 
-const newServer = ({
+const newServer = async ({
   clientOptions,
   req,
   res,
 }: {
   clientOptions: ClientOptions;
   req: express.Request;
   res: express.Response;
-}): McpServer | null => {
-  const server = newMcpServer();
+}): Promise<McpServer | null> => {
+  const server = await newMcpServer();
 
   try {
     const authOptions = parseAuthHeaders(req, false);
-    initMcpServer({
+    await initMcpServer({
       server: server,
       clientOptions: {
         ...clientOptions,
@@ -46,7 +46,7 @@ const newServer = ({
 const post =
   (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) =>
   async (req: express.Request, res: express.Response) => {
-    const server = newServer({ ...options, req, res });
+    const server = await newServer({ ...options, req, res });
     // If we return null, we already set the authorization error.
     if (server === null) return;
     const transport = new StreamableHTTPServerTransport();

packages/mcp-server/src/server.ts

@@ -17,23 +17,59 @@ import { HandlerFunction, McpTool } from './types';
 export { McpOptions } from './options';
 export { ClientOptions } from 'conductor-node';
 
-export const newMcpServer = () =>
+async function getInstructions() {
+  // This API key is optional; providing it allows the server to fetch instructions for unreleased versions.
+  const stainlessAPIKey = readEnv('STAINLESS_API_KEY');
+  const response = await fetch(
+    readEnv('CODE_MODE_INSTRUCTIONS_URL') ?? 'https://api.stainless.com/api/ai/instructions/conductor',
+    {
+      method: 'GET',
+      headers: { ...(stainlessAPIKey && { Authorization: stainlessAPIKey }) },
+    },
+  );
+
+  let instructions: string | undefined;
+  if (!response.ok) {
+    console.warn(
+      'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
+    );
+
+    instructions = `
+      This is the conductor MCP server. You will use Code Mode to help the user perform
+      actions. You can use search_docs tool to learn about how to take action with this server. Then, 
+      you will write TypeScript code using the execute tool take action. It is CRITICAL that you be 
+      thoughtful and deliberate when executing code. Always try to entirely solve the problem in code 
+      block: it can be as long as you need to get the job done! 
+    `;
+  }
+
+  instructions ??= ((await response.json()) as { instructions: string }).instructions;
+  instructions = `
+    The current time in Unix timestamps is ${Date.now()}.
+
+    ${instructions}
+  `;
+
+  return instructions;
+}
+
+export const newMcpServer = async () =>
   new McpServer(
     {
       name: 'conductor_node_api',
       version: '14.5.0',
     },
-    { capabilities: { tools: {}, logging: {} } },
+    {
+      instructions: await getInstructions(),
+      capabilities: { tools: {}, logging: {} },
+    },
   );
 
-// Create server instance
-export const server = newMcpServer();
-
 /**
  * Initializes the provided MCP Server with the given tools and handlers.
  * If not provided, the default client, tools and handlers will be used.
  */
-export function initMcpServer(params: {
+export async function initMcpServer(params: {
   server: Server | McpServer;
   clientOptions?: ClientOptions;
   mcpOptions?: McpOptions;

packages/mcp-server/src/stdio.ts

@@ -2,9 +2,9 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { initMcpServer, newMcpServer } from './server';
 
 export const launchStdioServer = async () => {
-  const server = newMcpServer();
+  const server = await newMcpServer();
 
-  initMcpServer({ server });
+  await initMcpServer({ server });
 
   const transport = new StdioServerTransport();
   await server.connect(transport);