Attio MCP Server

Instructions

Implementation Reference

• src/handlers/tool-configs/lists.ts:46-56 (registration)

  Tool registration config for 'get-list-details', including thin handler wrapper calling getListDetails and JSON formatter.

  getListDetails: {
    name: 'get-list-details',
    handler: async (listId: string) => {
      // Let Attio API decide if list ID is valid (supports UUIDs and slugs)
      return await getListDetails(listId);
    },
    formatResult: (result: AttioList) => {
      // Return JSON string
      return JSON.stringify(result);
    },
  } as ToolConfig,

• src/handlers/tool-configs/lists.ts:248-270 (schema)

  Tool definition including description and input schema for validating listId parameter.

  {
    name: 'get-list-details',
    description: formatToolDescription({
      capability:
        'Retrieve schema and configuration for a specific list (stages, fields, attributes).',
      boundaries: 'modify list structure or retrieve list entries.',
      constraints: 'Requires valid list UUID or slug; accepts both formats.',
      recoveryHint:
        'Use get-lists to discover available list IDs and slugs first.',
    }),
    inputSchema: {
      type: 'object',
      properties: {
        listId: {
          type: 'string',
          description: 'ID or slug of the list to get details for',
          example: 'sales-pipeline',
        },
      },
      required: ['listId'],
      additionalProperties: false,
    },
  },

• src/objects/lists/base.ts:52-106 (handler)

  Core handler function that fetches list details via generic or direct Attio API call with comprehensive error handling for 404, 422, etc.

  export async function getListDetails(listId: string): Promise<AttioList> {
    try {
      return await getGenericListDetails(listId);
    } catch (error: unknown) {
      const errorMessage = getErrorMessage(error) ?? 'Unknown error';
      if (process.env.NODE_ENV === 'development') {
        createScopedLogger('objects.lists', 'getListDetails').warn(
          'Generic getListDetails failed',
          { errorMessage }
        );
      }
  
      const api = getLazyAttioClient();
      const path = `/lists/${listId}`;
  
      try {
        const response = await api.get(path);
        const extracted = extract<AttioList>(response);
        return ensureListShape(extracted);
      } catch (apiError: unknown) {
        const status = getErrorStatus(apiError);
        if (status === 404) {
          throw new EnhancedApiError('Record not found', 404, path, 'GET', {
            resourceType: 'lists',
            recordId: String(listId),
            httpStatus: 404,
            documentationHint: 'Use search-lists to find valid list IDs.',
          });
        }
        if (status === 422) {
          const { InvalidRequestError } = await import(
            '../../errors/api-errors.js'
          );
          throw new InvalidRequestError(
            'Invalid parameter(s) for list operation',
            '/lists',
            'GET'
          );
        }
  
        const code = typeof status === 'number' ? status : 500;
        throw new EnhancedApiError(
          getErrorMessage(apiError) ?? 'List retrieval failed',
          code,
          path,
          'GET',
          {
            resourceType: 'lists',
            recordId: String(listId),
            httpStatus: code,
          }
        );
      }
    }
  }