Skip to content

Latest commit

 

History

History
360 lines (307 loc) · 9.91 KB

project-knowledge.md

File metadata and controls

360 lines (307 loc) · 9.91 KB

Airtable MCP Server Guide

Table of Contents

  1. MCP Server Tools Overview

    • Available Tools and Use Cases
    • Tool Dependencies and Workflow
    • Rate Limiting and Performance
    • Tool Authorization Requirements

  2. Base Management

    • Listing and Discovering Bases
    • Table Operations
    • Base Configuration
    • Access Control

  3. Field Management

    • Field Types and Options
    • Field Creation and Updates
    • Field Dependencies
    • Data Validation

  4. Record Operations

    • Reading and Querying Records
    • Creating and Updating Records
    • Batch Operations
    • Search and Filtering

MCP Server Tools Overview

Available Tools and Use Cases

  1. Base Management Tools

    a. list_bases

    • Purpose: Lists all accessible Airtable bases
    • Key Considerations:
      • Requires valid API key
      • Returns only bases with access permissions
      • Useful for initial discovery
    • Best Practices:
      • Cache base IDs for frequent operations
      • Verify base accessibility before operations
      • Handle pagination if many bases

    b. list_tables

    • Purpose: Lists all tables in a specified base
    • Key Considerations:
      • Requires base_id
      • Returns table metadata
      • Useful for table discovery
    • Best Practices:
      • Cache table IDs for frequent operations
      • Verify table existence before operations
      • Handle pagination for large bases

    c. create_table

    • Purpose: Creates a new table in an Airtable base
    • Key Considerations:
      • Requires base_id and table name
      • Can create multiple basic fields in one operation
      • Should be used first in any table creation workflow
      • Validate table name uniqueness in the base
    • Best Practices:
      • Start with essential basic fields only
      • Use clear, descriptive table names
      • Add proper table description
      • Follow naming conventions

    d. update_table

    • Purpose: Updates a table's name or description
    • Key Considerations:
      • Requires base_id and table_id
      • Can modify name and description
      • Existing data remains unchanged
    • Best Practices:
      • Verify table existence before update
      • Maintain naming consistency
      • Update documentation accordingly

  2. Field Management Tools

    a. create_field

    • Purpose: Adds a new field to an existing table
    • Key Considerations:
      • Requires both base_id and table_id
      • Add one field at a time for complex types
      • Field options must match type requirements
    • Best Practices:
      • Verify field creation before adding next
      • Use descriptive field names
      • Include field descriptions
      • Configure appropriate field options

    b. update_field

    • Purpose: Modifies existing field configuration
    • Key Considerations:
      • Can update name, description, and options
      • Some field types have immutable properties
      • Changes may affect existing data
    • Best Practices:
      • Backup data before significant changes
      • Test changes on sample records
      • Update documentation accordingly
      • Verify field behavior after changes

  3. Record Operation Tools

    a. list_records

    • Purpose: Retrieves records from a table
    • Key Considerations:
      • Supports filtering and sorting
      • Handles pagination
      • Can specify fields to return
    • Best Practices:
      • Use field selection for performance
      • Implement pagination for large datasets
      • Cache results when appropriate
      • Handle rate limits

    b. create_record

    • Purpose: Adds new records to a table
    • Key Considerations:
      • Validates field types
      • Handles required fields
      • Supports multiple records
    • Best Practices:
      • Validate data before submission
      • Handle batch operations efficiently
      • Verify record creation
      • Implement error recovery

    c. update_record

    • Purpose: Modifies existing records
    • Key Considerations:
      • Requires record ID
      • Partial updates supported
      • Field validation applied
    • Best Practices:
      • Verify record existence
      • Backup data before updates
      • Handle field type constraints
      • Log changes for audit

    d. delete_record

    • Purpose: Removes records from a table
    • Key Considerations:
      • Operation is irreversible
      • Can affect linked records
      • Supports batch deletion
    • Best Practices:
      • Verify record selection
      • Backup before deletion
      • Check dependencies
      • Implement confirmation

    e. search_records

    • Purpose: Finds records matching criteria
    • Key Considerations:
      • Supports complex filters
      • Can use multiple fields
      • Returns paginated results
    • Best Practices:
      • Optimize search criteria
      • Handle no results case
      • Implement pagination
      • Cache frequent searches

    f. get_record

    • Purpose: Retrieves a single record by ID
    • Key Considerations:
      • Direct record access
      • Returns all or selected fields
      • Efficient for single record ops
    • Best Practices:
      • Verify record existence
      • Handle missing records
      • Select needed fields only
      • Cache when appropriate

Tool Dependencies and Workflow

graph TD
    A[list_bases] --> B[list_tables]
    B --> C[create_table]
    C --> D[create_field]
    D --> E[update_field]
    B --> F[list_records]
    F --> G[create_record]
    F --> H[update_record]
    F --> I[delete_record]
    F --> J[search_records]
    F --> K[get_record]
    C --> L[update_table]
Loading

Rate Limiting and Performance

  1. API Constraints

    • Respect Airtable's rate limits
    • Implement exponential backoff
    • Handle throttling gracefully
    • Monitor API usage

  2. Operation Timing

    • Allow time between operations
    • Verify completion before next step
    • Handle timeouts appropriately
    • Log operation durations

  3. Resource Management

    • Monitor memory usage
    • Clean up temporary resources
    • Handle connection issues
    • Implement proper error recovery

Tool Authorization Requirements

  1. Authentication

    • Personal access token required
    • OAuth integration support
    • Proper scope configuration
    • Token management best practices

  2. Permissions

    • Base creator role needed
    • Verify write permissions
    • Check field-level access
    • Handle permission errors

Base Management

Table Management

Available Table Tools

  1. list_tables

    • Purpose: Lists all tables in a specified base
    • Key Considerations:
      • Requires base_id
      • Returns table metadata
      • Useful for table discovery
    • Best Practices:
      • Cache table IDs for frequent operations
      • Verify table existence before operations
      • Handle pagination for large bases

  2. create_table

    • Purpose: Creates a new table in an Airtable base
    • Key Considerations:
      • Requires base_id and table name
      • Can create multiple basic fields in one operation
      • Should be used first in any table creation workflow
      • Validate table name uniqueness in the base
    • Best Practices:
      • Start with essential basic fields only
      • Use clear, descriptive table names
      • Add proper table description
      • Follow naming conventions

  3. update_table

    • Purpose: Updates a table's name or description
    • Key Considerations:
      • Requires base_id and table_id
      • Can modify name and description
      • Existing data remains unchanged
    • Best Practices:
      • Verify table existence before update
      • Maintain naming consistency
      • Update documentation accordingly

Table Creation Workflow

  1. Initial Setup

    • Verify base access
    • Check table name availability
    • Plan table structure
    • Define primary fields

  2. Field Planning

    • Start with basic fields
    • Plan relationships with other tables
    • Consider computed fields
    • Define field dependencies

  3. Implementation Steps

    • Create table with basic fields
    • Add complex fields incrementally
    • Set up relationships
    • Configure views and permissions

Best Practices

  1. Table Design

    • Use clear, descriptive names
    • Follow consistent naming conventions
    • Include proper descriptions
    • Plan for scalability
    • Consider relationships early

  2. Data Organization

    • Group related fields logically
    • Use appropriate field types
    • Plan for future expansion
    • Consider data validation needs
    • Document table relationships

  3. Performance Considerations

    • Optimize field types for data size
    • Plan indexes for frequent queries
    • Consider record limits
    • Monitor table size
    • Handle large datasets efficiently

  4. Security and Access

    • Set appropriate permissions
    • Document access requirements
    • Plan sharing strategy
    • Consider data sensitivity
    • Implement proper controls

Common Patterns

  1. Master-Detail Tables

    • Primary table contains main records
    • Detail tables link to master
    • Use lookup fields for data access
    • Implement proper relationships

  2. Lookup Tables

    • Store reference data
    • Use for standardization
    • Minimize redundancy
    • Easy maintenance

  3. Junction Tables

    • Handle many-to-many relationships
    • Store relationship metadata
    • Enable complex queries
    • Maintain data integrity

Error Handling

  1. Creation Errors

    • Handle name conflicts
    • Validate field configurations
    • Check permissions
    • Provide clear error messages

  2. Update Errors

    • Verify table existence
    • Check field dependencies
    • Handle concurrent updates
    • Maintain data integrity

  3. Deletion Considerations

    • Check for dependencies
    • Backup important data
    • Handle cascading deletes
    • Verify permissions