Airtable OAuth MCP Server

Instructions

Implementation Reference

• src/airtable_mcp/mcp/server.py:141-184 (handler)

  The handler function for the 'list_tables' MCP tool. Authenticates via _get_authenticated_client, fetches the base schema using AirtableClient.get_base_schema(base_id), and returns either basic table identifiers or detailed info including fields based on the detail_level parameter.

  @self.mcp.tool(description="List tables in a specific base")
  async def list_tables(
      base_id: Annotated[str, Field(description="The Airtable base ID")],
      detail_level: Annotated[
          Literal["tableIdentifiersOnly", "withFieldInfo"],
          Field(
              description="Level of detail to include in response",
              default="tableIdentifiersOnly",
          ),
      ] = "tableIdentifiersOnly",
  ) -> list[dict[str, Any]]:
      """List tables in a specific base with optional field information."""
      client = await self._get_authenticated_client()
      schema = await client.get_base_schema(base_id)
  
      if detail_level == "tableIdentifiersOnly":
          return [
              {
                  "id": table.id,
                  "name": table.name,
              }
              for table in schema.tables
          ]
      else:  # withFieldInfo
          return [
              {
                  "id": table.id,
                  "name": table.name,
                  "description": table.description,
                  "primaryFieldId": table.primary_field_id,
                  "fields": [
                      {
                          "id": field.id,
                          "name": field.name,
                          "type": field.type,
                          "description": field.description,
                          "options": field.options,
                      }
                      for field in table.fields
                  ],
              }
              for table in schema.tables
          ]

• src/airtable_mcp/mcp/schemas.py:17-24 (schema)

  Pydantic schema definition for the input arguments of the list_tables tool, matching the inline annotations used in the handler.

  class ListTablesArgs(BaseArgs):
      """Arguments for list_tables tool."""
  
      base_id: str = Field(description="The Airtable base ID")
      detail_level: Literal["tableIdentifiersOnly", "withFieldInfo"] = Field(
          default="tableIdentifiersOnly",
          description="Level of detail to include in response",
      )

• src/airtable_mcp/mcp/server.py:57-58 (registration)

  The _register_tools() method is called during server initialization to register all MCP tools, including list_tables via its @self.mcp.tool decorator.

  # Register all MCP tools
  self._register_tools()