Set Up an MCP Contacts Server

Command references used in this guide: nylas mcp install for registering the server, nylas mcp serve for starting the STDIO proxy, nylas mcp status for confirming configuration, and nylas contacts search for the lookup logic the server exposes.

How do I install the Nylas MCP contacts server?

An MCP contacts server is a local process that exposes address-book operations — list contacts, search by company or email, read a single record — as tools an AI client calls over the Model Context Protocol. The Nylas CLI ships one built in. Installing it takes three steps and runs in under 60 seconds if Homebrew is already present.

The contact tools ride on the same server entry as the email and calendar tools, so no separate contacts install exists. MCP reached 97 million monthly SDK downloads by March 2026, and the public registry listed over 9,400 servers. For the mailbox counterpart, see the MCP email server guide.

The commands below add the CLI and authenticate the account. The OAuth flow opens a browser, stores the grant in ~/.config/nylas/, and refreshes tokens automatically every 3,600 seconds. For shell-script, PowerShell, and Go install methods, see the getting started guide.

# Install the CLI (macOS / Linux)
brew install nylas/nylas-cli/nylas

# Authenticate your account
nylas auth login

# Confirm the grant is active
nylas auth whoami

Once authenticated, register the server with nylas mcp install. The command detects which of the 5 supported assistants are installed, writes the correct JSON config, and for Claude Code adds the tool-permission entries so prompts are pre-approved. Run it once per machine.

# Register the server (interactive -- detects installed tools)
nylas mcp install

# Or target a specific assistant
nylas mcp install --assistant claude-code
nylas mcp install --assistant cursor
nylas mcp install --assistant windsurf
nylas mcp install --assistant vscode
nylas mcp install --assistant claude-desktop

# Or install for all detected assistants at once
nylas mcp install --all

How do I configure the contacts MCP server per tool?

The nylas mcp install command writes the config for you, but knowing what it writes helps with debugging. Every one of the 5 supported assistants uses the same JSON block: it points at the nylas binary and passes mcp serve as the startup argument. The server speaks JSON-RPC over STDIO, which all of them expect.

// The config block is identical for every tool -- only the file path differs
{
  "mcpServers": {
    "nylas": {
      "command": "nylas",
      "args": ["mcp", "serve"]
    }
  }
}

Place that block in the config file for your assistant. The mcp serve proxy injects the grant ID automatically, so the agent never needs to know which account it is reading. The table below lists where each of the 5 tools reads its config and whether the scope is project-local or global.

What contact tools does the MCP server expose?

The Nylas contacts MCP server exposes a read surface over the address book: list contacts and look up individual records by email, company, or phone. These tools map to the same logic as the nylas contacts command family, which auto-paginates past 200 records. Each call returns structured fields the agent can quote directly, such as name, email, and company.

The search capability is the one assistants reach for first, because finding a person precedes reading their detail. You can run the same query from the terminal to confirm the data the agent will see. The command below filters the address book by company and returns matching contacts with email addresses in under 1 second.

# Search the address book by company -- the data the search tool returns
nylas contacts search --company "Acme" --has-email --json

# Filter the full list by a single email address
nylas contacts list --email "alice@example.com" --json

When the assistant picks a record, it reads the full contact, which maps to the show command below. The nylas contacts show command takes a provider-native contact ID and prints every stored field. Pass --json to get a machine-readable payload the agent can parse without scraping a table.

# Read one contact in full by its provider-native ID
nylas contacts show <contact-id> --json

How do I verify the contacts MCP server works?

The nylas mcp status command checks all 5 supported assistants in one pass and reports which have the Nylas server configured. It reads each config file, confirms the nylas entry exists, and flags installed tools that are not yet connected. Run it right after install to catch a missing entry.

nylas mcp status

For an end-to-end test, open your assistant and ask it to find a known colleague by name or company. That request routes through the contact search tool and confirms the full chain: STDIO transport, grant injection, the API call, and field parsing. If the assistant returns the right email address, reads work end to end.

Here is the TL;DR detail. Contact sync is provider-dependent, so a contact created seconds ago may not appear yet. Google syncs the address book on a poll cycle of roughly 5 minutes, while Microsoft updates in near real time through Graph. If the agent cannot find a brand-new contact, wait one poll cycle and retry before assuming the server is broken.

Common errors and fixes

Roughly 90% of reported contacts MCP issues trace to 3 causes: the CLI is not authenticated, the assistant cached an old config, or a recently added contact has not synced yet. Each fix takes under 60 seconds, except the sync delay, which clears within one Google poll cycle.

Why use MCP instead of calling each contacts API directly?

MCP and direct contacts API calls solve different problems. MCP gives an AI client a standard way to discover and call address-book tools with zero glue code, while direct API calls are faster and cheaper per operation for bulk export. The best agents use both: MCP for interactive lookups during a conversation, direct API for batch sync. The protocol removes provider-specific quirks the agent would otherwise handle.

Contacts APIs diverge sharply between providers. Google's People API connections.list endpoint uses a personFields mask and resource names, while Microsoft Graph's list contacts endpoint returns OData entities with different field names. The vCard RFC 6350 standardizes the contact model, but each provider implements it differently. The MCP server normalizes all of this, so the agent calls one search tool regardless of backend, the same way the email server unifies sending.

Next steps

• Full command reference — every flag, subcommand, and example
• Set up an MCP email server — the mailbox counterpart that shares the same server entry
• Set up an MCP calendar server — expose availability and event tools to the same assistant
• Manage contacts from the terminal — the full list, search, create, and update reference
• Email MCP server for AI agents — tools, architecture, and example prompts
• Build an Agency Swarm email agent — the multi-agent alternative that wraps CLI subprocesses
• Sync email to SQLite — the batch-export pattern for when MCP lookups are too slow
• Model Context Protocol specification — the open protocol standard created and maintained by Anthropic
• Nylas MCP documentation — the upstream server reference
• vCard RFC 6350 — the contact data model providers implement differently