Notion MCP Server

Instructions

Implementation Reference

• src/openapi-mcp-server/mcp/proxy.ts:56-120 (registration)

  Registers the MCP handlers for listing tools (which includes generating the tool list with names like 'API-{operationId}', e.g., 'API-retrieve-a-page-property') and calling tools. This is where all tools, including the target one, are registered.
  private setupHandlers() { // Handle tool listing this.server.setRequestHandler(ListToolsRequestSchema, async () => { const tools: Tool[] = [] // Add methods as separate tools to match the MCP format Object.entries(this.tools).forEach(([toolName, def]) => { def.methods.forEach(method => { const toolNameWithMethod = `${toolName}-${method.name}`; const truncatedToolName = this.truncateToolName(toolNameWithMethod); tools.push({ name: truncatedToolName, description: method.description, inputSchema: method.inputSchema as Tool['inputSchema'], }) }) }) return { tools } }) // Handle tool calling this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: params } = request.params // Find the operation in OpenAPI spec const operation = this.findOperation(name) if (!operation) { throw new Error(`Method ${name} not found`) } try { // Execute the operation const response = await this.httpClient.executeOperation(operation, params) // Convert response to MCP format return { content: [ { type: 'text', // currently this is the only type that seems to be used by mcp server text: JSON.stringify(response.data), // TODO: pass through the http status code text? }, ], } } catch (error) { console.error('Error in tool call', error) if (error instanceof HttpClientError) { console.error('HttpClientError encountered, returning structured error', error) const data = error.data?.response?.data ?? error.data ?? {} return { content: [ { type: 'text', text: JSON.stringify({ status: 'error', // TODO: get this from http status code? ...(typeof data === 'object' ? data : { data: data }), }), }, ], } } throw error } }) }
• src/openapi-mcp-server/mcp/proxy.ts:78-119 (handler)

  The core handler function that executes any called MCP tool by mapping the tool name (e.g., 'API-retrieve-a-page-property') to the corresponding OpenAPI operation and proxying the HTTP request via HttpClient.
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: params } = request.params // Find the operation in OpenAPI spec const operation = this.findOperation(name) if (!operation) { throw new Error(`Method ${name} not found`) } try { // Execute the operation const response = await this.httpClient.executeOperation(operation, params) // Convert response to MCP format return { content: [ { type: 'text', // currently this is the only type that seems to be used by mcp server text: JSON.stringify(response.data), // TODO: pass through the http status code text? }, ], } } catch (error) { console.error('Error in tool call', error) if (error instanceof HttpClientError) { console.error('HttpClientError encountered, returning structured error', error) const data = error.data?.response?.data ?? error.data ?? {} return { content: [ { type: 'text', text: JSON.stringify({ status: 'error', // TODO: get this from http status code? ...(typeof data === 'object' ? data : { data: data }), }), }, ], } } throw error } })
• src/openapi-mcp-server/openapi/parser.ts:166-197 (schema)

  Generates MCP tool schemas and names from OpenAPI spec. Tool names are constructed as 'API-{operationId}' (truncated if needed), input schemas from operation parameters and requestBody. Called during proxy initialization to define all tools including 'API-retrieve-a-page-property'.
  convertToMCPTools(): { tools: Record<string, { methods: NewToolMethod[] }> openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }> zip: Record<string, { openApi: OpenAPIV3.OperationObject & { method: string; path: string }; mcp: NewToolMethod }> } { const apiName = 'API' const openApiLookup: Record<string, OpenAPIV3.OperationObject & { method: string; path: string }> = {} const tools: Record<string, { methods: NewToolMethod[] }> = { [apiName]: { methods: [] }, } const zip: Record<string, { openApi: OpenAPIV3.OperationObject & { method: string; path: string }; mcp: NewToolMethod }> = {} for (const [path, pathItem] of Object.entries(this.openApiSpec.paths || {})) { if (!pathItem) continue for (const [method, operation] of Object.entries(pathItem)) { if (!this.isOperation(method, operation)) continue const mcpMethod = this.convertOperationToMCPMethod(operation, method, path) if (mcpMethod) { const uniqueName = this.ensureUniqueName(mcpMethod.name) mcpMethod.name = uniqueName mcpMethod.description = this.getDescription(operation.summary || operation.description || '') tools[apiName]!.methods.push(mcpMethod) openApiLookup[apiName + '-' + uniqueName] = { ...operation, method, path } zip[apiName + '-' + uniqueName] = { openApi: { ...operation, method, path }, mcp: mcpMethod } } } } return { tools, openApiLookup, zip } }
• src/openapi-mcp-server/mcp/proxy.ts:48-54 (registration)

  In the MCPProxy constructor, converts the Notion OpenAPI spec to MCP tools using OpenAPIToMCPConverter, storing the tool definitions and lookup for name-to-operation mapping.
  const converter = new OpenAPIToMCPConverter(openApiSpec) const { tools, openApiLookup } = converter.convertToMCPTools() this.tools = tools this.openApiLookup = openApiLookup this.setupHandlers() }
• src/openapi-mcp-server/mcp/proxy.ts:122-124 (helper)

  Helper to resolve tool name (operationId like 'API-retrieve-a-page-property') to the OpenAPI operation details (method, path, etc.).
  private findOperation(operationId: string): (OpenAPIV3.OperationObject & { method: string; path: string }) | null { return this.openApiLookup[operationId] ?? null }