Notion MCP Server

Instructions

Implementation Reference

• src/openapi-mcp-server/mcp/proxy.ts:78-119 (handler)

  The MCP 'callTool' request handler that executes the tool logic for 'API-retrieve-a-page-property'. It resolves the tool name to the corresponding OpenAPI operation and delegates execution to 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/client/http-client.ts:104-190 (helper)

  Helper function that performs the actual HTTP request for the tool using a generated OpenAPI client (openapi-client-axios). Calls the typed operation function like api['retrieve-a-page-property'](params).

  async executeOperation<T = any>(
    operation: OpenAPIV3.OperationObject & { method: string; path: string },
    params: Record<string, any> = {},
  ): Promise<HttpClientResponse<T>> {
    const api = await this.api
    const operationId = operation.operationId
    if (!operationId) {
      throw new Error('Operation ID is required')
    }
  
    // Handle file uploads if present
    const formData = await this.prepareFileUpload(operation, params)
  
    // Separate parameters based on their location
    const urlParameters: Record<string, any> = {}
    const bodyParams: Record<string, any> = formData || { ...params }
  
    // Extract path and query parameters based on operation definition
    if (operation.parameters) {
      for (const param of operation.parameters) {
        if ('name' in param && param.name && param.in) {
          if (param.in === 'path' || param.in === 'query') {
            if (params[param.name] !== undefined) {
              urlParameters[param.name] = params[param.name]
              if (!formData) {
                delete bodyParams[param.name]
              }
            }
          }
        }
      }
    }
  
    // Add all parameters as url parameters if there is no requestBody defined
    if (!operation.requestBody && !formData) {
      for (const key in bodyParams) {
        if (bodyParams[key] !== undefined) {
          urlParameters[key] = bodyParams[key]
          delete bodyParams[key]
        }
      }
    }
  
    const operationFn = (api as any)[operationId]
    if (!operationFn) {
      throw new Error(`Operation ${operationId} not found`)
    }
  
    try {
      // If we have form data, we need to set the correct headers
      const hasBody = Object.keys(bodyParams).length > 0
      const headers = formData
        ? formData.getHeaders()
        : { ...(hasBody ? { 'Content-Type': 'application/json' } : { 'Content-Type': null }) }
      const requestConfig = {
        headers: {
          ...headers,
        },
      }
  
      // first argument is url parameters, second is body parameters
      const response = await operationFn(urlParameters, hasBody ? bodyParams : undefined, requestConfig)
  
      // Convert axios headers to Headers object
      const responseHeaders = new Headers()
      Object.entries(response.headers).forEach(([key, value]) => {
        if (value) responseHeaders.append(key, value.toString())
      })
  
      return {
        data: response.data,
        status: response.status,
        headers: responseHeaders,
      }
    } catch (error: any) {
      if (error.response) {
        console.error('Error in http client', error)
        const headers = new Headers()
        Object.entries(error.response.headers).forEach(([key, value]) => {
          if (value) headers.append(key, value.toString())
        })
  
        throw new HttpClientError(error.response.statusText || 'Request failed', error.response.status, error.response.data, headers)
      }
      throw error
    }
  }

• src/openapi-mcp-server/mcp/proxy.ts:58-75 (registration)

  The 'listTools' request handler that dynamically registers 'API-retrieve-a-page-property' (generated as 'API-{operationId}') with its schema and description from the OpenAPI spec.

  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 }
  })

• src/openapi-mcp-server/mcp/proxy.ts:48-51 (schema)

  Generates the tool schemas and operation lookup map (including for 'API-retrieve-a-page-property') from the loaded OpenAPI spec using OpenAPIToMCPConverter.convertToMCPTools().

  const converter = new OpenAPIToMCPConverter(openApiSpec)
  const { tools, openApiLookup } = converter.convertToMCPTools()
  this.tools = tools
  this.openApiLookup = openApiLookup

• src/openapi-mcp-server/mcp/proxy.ts:122-124 (helper)

  Helper that resolves the tool name 'API-retrieve-a-page-property' to the exact OpenAPI operation details.

  private findOperation(operationId: string): (OpenAPIV3.OperationObject & { method: string; path: string }) | null {
    return this.openApiLookup[operationId] ?? null
  }