---
title: "MCP for Airtable"
description: "Connect Claude Code to your Airtable base so it can read, create, and update records on your behalf"
tags: ["mcp", "integration", "data"]
difficulty: "intermediate"
time_estimate: "30 min"
---
# MCP for Airtable

## What You'll Build

- A working MCP connection between Claude Code and an Airtable base
- A read-only "sanity check" that confirms the connection works
- A real multi-step task where Claude Code reads *and* writes Airtable records on its own

## Why This Quest

In Unit 1's level-up exercise, you talked to Airtable from Python — generate a token, make HTTP requests, parse JSON, handle errors. It worked, but it was a lot of plumbing.

Airtable's MCP server handles all that plumbing for you. Once it's set up, Claude Code can talk to Airtable directly. You stop writing request code and start writing sentences like *"find every bird in the Birds table that's missing a summary, and fill it in."*

If you haven't read [What Is MCP?](/XTfOPd-OTaKrncI860x0dg) yet, that's a good five-minute warm-up — it explains what an MCP server actually *is*. This quest assumes you're good with that.

## Prerequisites

- Completed Module 2.2 (Claude Code)
- The Airtable Personal Access Token (PAT, i.e. API key) you used during the Unit 1 level-up exercise

> **Read the docs first.** Skim [Airtable's official MCP server documentation](https://support.airtable.com/docs/using-the-airtable-mcp-server) before you start. It covers prerequisites, required scopes, safety tips, and how to manage which bases the integration can see after it's connected.

## The Shared Base

For this quest, we'll use the same shared Airtable base as before so everyone's pointing at the same data. If you don't have the base ID or PAT yet, DM Jungyoon or Dani.

If you need to use your own base instead, DM Jungyoon or Dani and we'll set you up with a base and PAT.

## Step 1: Install the Airtable MCP Server

Airtable hosts their own MCP server at `https://mcp.airtable.com/mcp`, so there's nothing to download or run locally — Claude Code just talks to that URL over HTTP, sending your Personal Access Token on each request.

Claude Code has a command for adding MCP servers to your config — no hand-editing required. In your terminal, run:

claude mcp add --transport http --scope local airtable https://mcp.airtable.com/mcp \
  --header "Authorization: Bearer pat_YOUR_TOKEN_HERE"

Replace `pat_YOUR_TOKEN_HERE` with your actual token (starts with `pat...`).

What that command is doing, piece by piece:

- `claude mcp add airtable` — registers a new MCP server and calls it `airtable`
- `--transport http` — tells Claude Code to connect over HTTP instead of spawning a local process
- `--scope local` — binds this server to the current project folder only, so it's loaded when you run `claude` here but not in your other projects (more on this below)
- `https://mcp.airtable.com/mcp` — the URL of Airtable's hosted MCP server
- `--header "Authorization: Bearer ..."` — sends your PAT on every request so Airtable knows who you are

Under the hood this appends an entry to `~/.claude.json` similar to the JSON block you saw in [What Is MCP?](/XTfOPd-OTaKrncI860x0dg) — just with an HTTP URL and header instead of a local command.

**Why `--scope local`?** Claude Code has three scopes for MCP servers: `user` (loaded in every project on your laptop), `project` (shared with teammates via a `.mcp.json` checked into git), and `local` (just this project folder, just you). We want `local` here for two reasons. First, your Airtable PAT sits in plaintext in the config — if we used `project`, that file would get committed to git, which is a great way to leak a token to the internet. Second, you don't want Airtable tools quietly loaded in every unrelated project you open in Claude Code; local scope keeps the surface area small and intentional. Treat `user` scope as a last resort — only reach for it when a server genuinely belongs in every session.

## Step 2: Restart Claude Code and Verify

Quit Claude Code if it's running, then start a new session in your project folder:

claude

Once it's up, type:

/mcp

You should see `airtable` in the list with a connected status. If you don't, jump to [Troubleshooting](/fA-kW0sWSKWsy-_x1wOAIQ#Troubleshooting) below.

## Step 3: Read-Only Sanity Check

Still inside Claude Code, try a purely read-only prompt:

Using the Airtable base YOURBASEID, how many records does the Birds table have?

Watch what happens. Claude Code should call an Airtable tool like `list_records` — you'll see it ask for permission the first time, then print a count back.

This is the moment where MCP stops being abstract. You asked in English. It read your data.

If you get a clean answer here, your connection works. If Claude Code can't find Airtable tools or the server errors out, see [Troubleshooting](#troubleshooting) below.

## Step 4: Understand the Permission Model

Before you let Claude Code loose on a writable task in Step 5, it's worth understanding *why* this is safe. The shared class token is already configured with read + write scopes, so you won't be editing any permissions here — but every time you connect a new MCP server later (GitHub, Google Drive, etc.), you'll want to be able to reason about what it can and can't do. Airtable MCP is a clean example.

There are three layers of permission sitting between your prompt and your data:

**Layer 1 — What tools the server exposes.** Inside Claude Code, ask:

What Airtable tools do you have available?

Claude will list things like `list_records`, `search_records`, `create_record`, `update_records`, `delete_records`, `list_bases`, `describe_table`. This surface is decided by *Airtable* — they chose which operations to expose. If a tool isn't on this list, no prompt can make it happen.

**Layer 2 — What scopes the token has.** Every tool call is checked against the PAT's scopes. The class token is configured with all four of the scopes Airtable's docs list:

- `data.records:read` — read rows
- `data.records:write` — create/update/delete rows
- `schema.bases:read` — see table and field structure
- `schema.bases:write` — create/rename tables and fields

If a tool tried to write but the token were read-only, the call would come back with a `403`. Scopes are set at [airtable.com/create/tokens](https://airtable.com/create/tokens) when you create a PAT.

**Layer 3 — Which bases the token can see.** Even with the right scopes, a PAT only works on bases that were explicitly added to it. The class token is restricted to the class base. In your own account you can see (and edit) this at Profile → Integrations → Third-party Integrations.

On top of those three, Claude Code itself asks for your approval before every write in Step 5 — a fourth checkpoint you control in the moment.

**The mental model to walk away with:** whenever you connect a new MCP server, ask three questions. *What tools does the server offer? What scopes does the credential grant? Which resources is it scoped to?* Server surface, credential scope, resource scope. If you can answer those three, you know what you're handing the agent.

## Step 5: A Real Multi-Step Task

Here's where MCP earns its keep. Pick a task that requires *chaining* several operations together — something you'd have written a whole Python script for in Unit 1.

For example, using a Birds table in the class base:

In base YOURBASEID, look at the Birds table. For any row that's missing a "summary" field, read the bird's existing fields and write a one-sentence summary of what makes this bird poetically interesting. Update the row in place.

Claude Code will:

1. Read the table schema (so it knows which fields exist)
2. Query records where `summary` is empty
3. For each one, compose a summary from the other fields
4. Write the summary back

Watch it work. It'll ask before each write — say yes (or enable auto-approval if you trust it). You're now doing something that used to take a notebook full of code, in a single prompt.

### Other Starter Ideas

- **Deduplicate**: "Find records in the Birds table where the name appears more than once, and flag them for review."
- **Generate from data**: "Read the Poems table, then create a new record in the Images table describing what a cover image for each poem should look like."
- **Reconcile two sources**: "Compare the birds in Airtable to the birds in `data/birds.json` on disk. Tell me which names don't match." *(Requires the filesystem MCP server too — a natural next quest.)*

## Staying Safe

A few habits worth forming now, before you're doing this on real data:

- **Scope your token to one base.** Don't give it "All current and future bases" access just because it's easier.
- **Start read-only, graduate to write.** Every time you connect a new MCP server to sensitive data, do the read-only loop first.
- **Read proposed writes before approving.** Claude Code will ask. Actually look at the change. It's very fast and right most of the time, but when it's wrong it can be wrong at scale — that's the downside of chaining.
- **Duplicate the base if you're nervous.** Airtable makes this a one-click operation. Play in the copy.
- **Audit which bases the integration can see.** In Airtable, go to your profile → Integrations → Third-party Integrations, pick your MCP integration, and add or remove bases as needed. This is a second line of defense on top of token scopes.

## Troubleshooting

**`/mcp` shows airtable as failed or disconnected.** Usually one of three things:

1. **Typo in the token or header.** The `Authorization` header must be exactly `Bearer ` followed by your PAT. Re-run `claude mcp add` (the old entry will be replaced) if you suspect a typo.
2. **Token has no scopes or no base access.** Go back to [airtable.com/create/tokens](https://airtable.com/create/tokens) and check — you need at least `data.records:read` and `schema.bases:read` for the read-only flow.
3. **Can't reach `mcp.airtable.com`.** Try `curl -I https://mcp.airtable.com/mcp` in your terminal — if that fails, it's a network issue, not an MCP one.

**Claude Code says it doesn't have Airtable tools.** You probably started Claude Code *before* running `claude mcp add`. Quit and reopen.

**Calls fail with 403 / unauthorized.** The token's scopes or base access don't cover what the server is trying to do. Add the missing scope in Airtable and try again.

**You want to remove the server.** `claude mcp remove airtable`.

## One More Thing: MCP vs. The Airtable API

You might be wondering: *"So if I build a Next.js app that shows my bird encyclopedia, is MCP how it talks to Airtable?"*

No — and this is worth pinning down, because it trips a lot of people up.

| | Who's talking to Airtable | When |
|---|---|---|
| **MCP (this quest)** | Claude Code, on your laptop, while you're coding | At **dev time** — you're exploring, prototyping, seeding, debugging |
| **Airtable API (next quest)** | Your deployed Next.js app's server code | At **runtime** — every time a real user visits a page |

Your deployed web app doesn't have Claude Code running inside it. It talks to Airtable directly via the Airtable REST API from a Next.js API route — the same "API routes for code" pattern from History of the Web.

MCP is an incredibly useful sidekick *while you're building* that app (Claude Code can inspect the schema, generate types, scaffold the API routes for you). But the app itself uses the Airtable API at runtime.

## Key Concepts

| Term | What It Means |
|------|--------------|
| Personal Access Token (PAT) | Airtable's scoped API credential — what the MCP server uses to authenticate as you |
| Scope | A permission on a token (e.g. `data.records:read`) that limits what the holder can do |
| Base ID | The `app...` identifier that uniquely names an Airtable base |
| `claude mcp add` | Claude Code command that registers a new MCP server in your config |
| MCP server scope | Claude Code setting (`user`, `project`, or `local`) that controls where a server is loaded — separate from token scopes |
| HTTP transport | How Claude Code talks to a remotely hosted MCP server (like Airtable's) — no local process to spawn |
| Read-only sanity check | The habit of first testing a new MCP connection without write permissions |
| Chaining | When an LLM calls several MCP tools in sequence to finish a multi-step task |