MCP Setup

What is MCP?

Model Context Protocol is an open standard that enables AI assistants to interact with external systems through a unified interface. In n8v, MCP servers provide n8v with additional capabilities beyond code editing.

Connect Claude or ChatGPT to n8v

Use https://n8v.online/mcp with OAuth. This lets another assistant find and read your n8v chats, message an agent, start work on a connected repository and wait for its reply. Your account must have AI assistants enabled under Settings > API & MCP.

• Claude: open Customize > Connectors > Add custom connector. Enter n8v and the server URL, select Sign in now and Claude's published identity, then connect and approve access. Team workspaces may require an administrator to add the connector first.
• ChatGPT: open Plugins, select the plus button and Add custom MCP server. Enter n8v and the URL, choose OAuth, then Create as a plugin. Sign in, approve access and install it. In a new chat, type @ and select n8v. Availability follows your account and workspace policy.

No OAuth client secret is needed. Approve only the permissions you want to grant. Disconnect under API & MCP to revoke access immediately.

What you approve belongs to the app, not to one sign-in: approve a permission once at the consent screen and every connection of that app has it, on every device. When a tool seems to be missing, the assistant can call whoami: every tool and connector with whether this connection may use it and, if not, why and what fixes it. The same list is under What it can do for each key and connected app in Settings > API & MCP. See What an assistant can read.

With the permission to read your files, the assistant can also read a repository without starting a chat: repo_overview, repo_tree and repo_file for its structure, and repo_commits, repo_commit, repo_branches, repo_tags and repo_pulls for its history. Read-only; environment files, keys and credentials are never returned. Switch it off under Settings, API, Reading repositories. Try: "What changed in the billing folder this week?"

To choose a model, the assistant can call list_models: the models your account can use, by agent, and your default. See Model access. Where model capabilities are on, recommend_model ranks them for a kind of work and model_capabilities shows each model's scores with their source and date. See Model capabilities. Admins who connect with an API key that has the model access scopes also get model_access, access_activity and set_model_access; a connected app never does.

To see what every agent is doing right now, the assistant can call now: each running chat's step in flight and for how long, its turn so far, and the chats that wait for you, as the Now board in the app shows them. stop_chat stops a turn, fast_forward sends your saved Fast-Forward prompt, and archive_chat archives a chat (its agent stops) or brings it back.

Where repository instructions are on, get_instructions reads what every agent on a repository is told, and what is in force on one chat. set_instructions changes a repository's texts, or with propose leaves a proposal you confirm in n8v. fast_forward then sends your prompt with the repository's Fast Forward instructions, takes a message for this press, and with dry_run returns the composed message without sending. update_chat takes instructions for one chat's own override. Try: "What would Fast Forward send on that chat?" See Repository instructions.

To find chats, the assistant filters list_chats in one call instead of paging: by status (error, complete, running, needs_you and more), a from and to date, an organization (its key) or an automation (its name). Asked "what failed this week?", it calls list_chats with status ["error"] and from set to Monday. To tidy up, update_chat renames a chat, pins or unpins it, marks it read or unread, or changes the model its next messages run on, and bulk_chats archives, restores, marks read or unread, or stops up to 50 chats at once. Settings, API, Chat controls switches these off and on for every assistant and key of your account.

The assistant organizes chats as you do in the list: with tags (several per chat, each with a color) and topics (the list's categories, one per chat). update_chat takes add_tags, remove_tags and topic; bulk_chats takes the actions tag, untag and set_topic for up to 50 chats; list_chats filters by tags (any of them) and topic ("No topic" for chats in none) and shows each chat's. list_tags, create_tag, update_tag and delete_tag manage the tags themselves; list_topics, create_topic, update_topic and delete_topic the topics. It names them as you do, in any case. Try: "Tag the failing chats from this week as urgent" or "Put every chat on the billing repo under the Payments topic." These tools are offered while tags or topics are on for your account, and Chat controls switches them off with the rest. See Tags and topics.

Every chat's pull request comes with it: read_chat, list_chats and now say whether it is open, a draft, merged or closed, whether CI passes or fails, whether it has conflicts, and whether the change is on main and live in production. pull_request_status gives one in full: the review, every check with the link to its log, the commit on main, and each production environment. To find chats by it, list_chats takes pr_state, checks and conflicts, and date_field merged. Try: "What merged today, and is it live?" or "Which pull requests are failing CI?" It reads GitHub through the n8v GitHub App, read-only; when the app may not read checks or deployments yet, the answer says so and where to approve it. Switch it off under Settings, API, Reading chats, Pull requests and CI. See Pull request and CI for the same over the API.

n8v cannot tell an assistant when work finishes, so it catches up instead: catch_up lists what happened since it last looked, oldest first, in words it can read out: chats that finished, failed or wait for you (a plan to approve, or a chat that stopped progressing, with the reason and the next step), automation runs, and what your organizations ask you. It keeps the next_cursor it gets and passes it as since next time, so each event comes once; without since it reads the last 24 hours. Try: "What happened while I was away?" The same events reach your own endpoints as webhooks.

To find something said in any chat, such as a prompt you send often, the assistant can call search_messages: your messages and the agents' replies (never tool output), newest first, as snippets with message ids. It filters by author (owner, agent or any), chat, repository, organization, dates and archive, and pages with cursor. Words of 3 or more characters match as prefixes, "quotes" match a phrase, -word excludes and or matches either. list_chats still matches titles and repositories.

Chats can be long, so the assistant reads light first. read_chat takes only: all (the default, as before), owner (only what you wrote) or summaries (the agent's final summary of each turn). read_message opens one message or tool step in full by its id, a tool call with its input and output, in pages of up to 60,000 characters (offset, max_chars). Clipped text in read_chat names the message_id that shows it all.

Message search is on for every account; an admin can switch it off under Settings > API & MCP, Reading chats. Off, search_messages and read_message are not offered and read_chat reads everything. Both tools need chats:read (Read chats), as read_chat does. See Search messages for the same calls over the API.

To say what you spent and on what, the assistant can call usage: what your agents' work cost at list price, what n8v took from your credits, tokens and agent time, by model, chat, organization, automation or period, compared with the period before. stats reads the numbers on your Stats page. Both need the permission to read your chats, and the organization view also the one to read organizations. Switch them off under Settings, API, Usage and statistics. Try: "What did I spend this week, and on what?"

Before starting many chats, the assistant can call sandboxes: how many of your tasks run now, of how many may run at once, and how many wait. Chats over the limit wait and start as soon as one finishes. It needs the permission to read your chats. Try: "How many agent environments am I running?"

Your prepared prompts work over MCP as they do in the composer: list_prompts and read_prompt read them with their variables, start_chat_with_prompt starts a chat with one on a repository, branch and model, and send_prompt sends one into a chat. The assistant fills in {{variables}}, can add a note, and with dry_run reads the exact message back before sending it. create_prompt, update_prompt and delete_prompt change the library. Try: "Send my review prompt to the login chat." Turn this off, for your account alone, under Settings > API & MCP > Prepared prompts. See Prepared prompts.

With supervisors on your account, the assistant can manage them too: list_supervisors, read_supervisor and supervisor_activity (every decision it made and message it sent) read them; create_supervisor, update_supervisor, pause_supervisor, resume_supervisor and delete_supervisor change them. Name a supervisor by its id or its name, so "pause the release supervisor" works. They need the supervisor permissions: approve them once at the consent screen, by connecting n8v again from the assistant, and every connection of that app has them. Turn them off for every assistant and key in Settings > API & MCP, Supervisors. See Supervisors.

Where supervisors on a time box are enabled for your account, create_supervisor and update_supervisor also take a time box (for_minutes or until) and powers, the whole of what the supervisor may do on its own. stop_supervisor ends one for good and answers its handover, start_chats_under_supervisor starts chats already under one (it also needs the permission to start chats), and supervisor_timeline shows everything done to it and by it. Only you, or the assistant acting for you, set or extend a time box and its powers; a supervisor cannot. See Supervisors on a time box.

Peer messaging lets the assistant connect your chats so their agents work things out directly:

• list_peer_chats lists the chats a message can reach now, with how soon it would arrive and what each chat last said.
• connect_chats introduces two chats to each other, with an optional brief of what they should settle together.
• send_peer_message sends a message to one chat in another's name; the answer comes back to the chat it was sent from.
• read_peers reads what a chat said with your other chats, set_peer_reach takes a chat out of peer messaging or puts it back, and cancel_peer_message cancels a message that has not reached its agent.

connect_chats and send_peer_message take an optional idempotency_key, so an assistant that retries sends nothing twice. These tools are not listed while peer messaging is off for your account (Settings, Agent, Peer messaging).

Try: "Connect my checkout chat with the payments API chat, and have them agree on the webhook payload."

With organizations, the assistant can also set them up when you turn on Manage your organizations while connecting: create_organization, update_organization (name, description, the context every agent is told, and caps), archive_organization (stops it; reversible) and hide_organization (out of your sidebar, still running). read_agent shows what an agent knows and the exact instructions it runs with; create_agent, update_agent (including who it reports to, its model and budget) and remove_agent change the team; add_routine, update_routine and remove_routine its schedules; add_goal, update_goal and remove_goal the goals. Try: "Set up a tax adviser in Immersive Investments that files the quarterly VAT return."

The assistant attaches files to an organization's work (PDFs, CSVs, Markdown, images, office documents; up to 25 MB through n8v) with upload_file, then passes the file it answers to add_work or comment_on_work. A file up to 2 MB goes in one call, as text or base64. A larger one gets an upload_url on storage; an assistant whose machine cannot reach storage, such as a cloud session that allows few hosts, sends the bytes over the MCP connection itself with upload_file_part (parts of up to 2 MB, the last with the file's SHA-256), or PUTs them to n8v_upload_url on n8v's own domain. n8v checks each file's size, hash and content, scans text for keys and tokens, and records every upload, part and attachment in your activity log.

Turn on Use your connectors to let the assistant call connectors you connected in n8v, such as a Gmail mailbox or Cloudflare. Nothing passes until you turn a connector on under Settings > API & MCP, Connectors for assistants. That allows its tools known to only read; any other tool passes only once you tick it. list_connectors shows what it may call, each connector with the account it belongs to (a Gmail mailbox by its address, another connector by its workspace or account name) and whether its sign-in is ok or expired; call_connector calls one tool, naming the connector by that account, its name or its id. An account must match exactly one connection: with none or several, nothing is called. Each call is in your activity log, without what it read.

Turn on Read your files to let the assistant look at files of your repositories and chats (a key limited to some repositories reads only those). list_files finds a file (path, glob) and gives each a file object; read_file returns the whole original: a PDF as the PDF itself, an image as an image, text as text. Over the limits (start: 10 MB and 30 PDF pages) it says the size, the limit and how to read a page range; mode: "pages" returns page images and the text, five pages a call, with the next range to ask for. Claude does not take an embedded PDF from a tool, so for Claude read_file returns page images and text unless you ask for mode: "original". Environment files, keys and credentials are never readable, and every read is in your activity log without the content. An admin sets the limits under Admin, File access, and turns the feature on per account with the mcpFiles flag.

To attach a file to a Gmail draft, the assistant gives gmail_draft an attachments list of file objects: n8v fetches and attaches each one itself, so the file never passes through the model, and answers with a receipt per file (name, type, size, pages, SHA-256 of what Gmail holds and of the source, and whether they match). Before anything is sent, verify_draft shows what the draft really holds, recipients, subject, text and every attachment, and flags one that is wrong, missing or changed; read_file opens an attachment exactly as it sits in the draft. Opening a draft or an attachment needs gmail_read ticked for that mailbox.

Where artifacts are on for your account (early access), the assistant can keep what it makes in n8v. artifact_publish publishes one HTML page or a small package (HTML, CSS, JavaScript, images, fonts, data) as a new artifact, or as a new version of one: at most 100 files, 10 MB a file and 25 MB a version, of which 3 MB may be sent inline; a PDF or a data file put into an organization with upload_file goes in by reference, without sending it again. artifact_list lists your artifacts and those shared with your organizations, artifact_read shows one with its versions, files, chats and share link, artifact_file reads one file, and artifact_diff says what changed between two versions. artifact_share sets who sees an artifact (private, its organization, or a link behind a sign-in) and artifact_archive archives or restores it; the assistant does either only when you ask. A page opens in an isolated frame on a site of its own and reaches nothing of your n8v account. Every file is scanned for secrets before it is stored, and every call is in your activity log without a file's content. Reading needs Read your artifacts (artifacts:read); publishing, sharing and archiving need Publish artifacts (artifacts:write). To hand an artifact to a new chat's agent, the assistant passes its id in start_chat's artifacts, up to 5 a chat. Try: "Publish this report to n8v", then "What changed in its last version?" See Artifacts.

These are switches of their own on the consent screen, off until you turn them on. Already connected? Connect n8v again in Claude or ChatGPT once and turn them on: every connection of that app then has them, on every device.

When a chat stops on an error, read_chat says why and what a retry can do (last_error). retry_chat runs it again, or sends a message refused for its model again with another one; the chat records which model and that it came over MCP.

When a chat stops because its agent environment could not start, or seems stuck, the assistant can call sandbox_health: whether the agent environment runs, is paused or could not be resumed, its memory and disk, the last work n8v saved (every few minutes and at the end of each turn, to a hidden ref of the repository) and whether the work is recoverable without the agent environment. resume_sandbox tries again with backoff, rebuild_sandbox gives the chat a fresh agent environment from its last save and continues the chat, and export_work saves what an agent environment that can still be read holds, with links (and the patch, if asked). They are offered while Save work in progress is on in Settings, General. Try: "Why did my themes chat stop, and can you get its work back?" See Agent environment health and recovery.

To manage your automations, the assistant can call list_automations (each one with a warning when its model can no longer run), read_automation and list_automation_runs (why each run failed), and create_automation, update_automation, pause_automation, run_automation and delete_automation. They need the automations access, which an assistant connected before it existed gets by connecting again. See Automations API.

When a chat waits, read_queue says why (your agent environment slots, a subscription's usage limit and when it resets, the line for a free agent environment, its own turn or a schedule) and lists its queued messages with the model each runs on; edit_queue edits, removes, reorders or clears them. fork_chat forks a chat, or restarts one whose agent environment broke, from its first message and a summary. See Queue, fork and restart.

Try: "List my n8v chats", then "Read the chat about login", or "Find the prompt I use to deploy staging". ChatGPT research can use search and fetch for citable transcripts. Search matches active chat titles and repositories, then up to 20 messages that match what was said; fetch returns a bounded page (for a message, the page ending at it) and an older_id when more history is available. The assistant can fetch that id to continue.

Connection labels can change. Current official instructions: Claude and ChatGPT.

Configuring MCP Servers

Managed OAuth and bearer connections

Managed connections support public HTTPS MCP endpoints with no authentication, OAuth 2.1, or a bearer token. Credentials are encrypted by n8v and are not added to the environment's MCP JSON or exposed to the agent environment.

For Gmail, select the Gmail preset and enter the web OAuth client ID and secret from the Google Cloud project where the Gmail API and Gmail MCP API are enabled. Add the callback URL shown in n8v to the OAuth client's authorized redirect URIs, then choose Save and sign in. Gmail's official remote endpoint is https://gmailmcp.googleapis.com/mcp/v1.

Cloudflare (early access)

Cloudflare connects on a scoped API token, so agents can manage Access applications and policies, DNS records, cache, and Pages and Workers deployments. In Skills & MCPs, choose Connect MCP server, then Cloudflare. Open the prefilled link to create a token in Cloudflare (Account Settings Read, Zone Read, DNS Edit, Cache Purge, Access: Apps and Policies Edit, Cloudflare Pages Edit, Workers Scripts Edit), narrow it to the accounts, zones and permissions you want, and paste it. n8v checks the token with Cloudflare, stores it encrypted, and never shows it again. Use Replace token to rotate it. A new Cloudflare connection is not active in chats by default: turn it on for a chat, or switch on Default active.

Agents get each action as its own tool, so you can allow reading DNS without allowing deletes. Destructive tools ask for proof: deleting a DNS record, an Access application or a policy needs its name or domain repeated, a policy that lets everyone in needs allow_public: true, and purging a whole zone needs everything: true. To upload new Worker code, agents use wrangler deploy in the repository.

Mail (early access)

Mail connects an address on n8v's own mail domain, so agents and assistants can search and read what arrives for it and prepare messages from it. It is limited to n8v's own team for now. In Skills & MCPs, choose Connect MCP server, then Mail, and enter the address. There is nothing to paste: n8v sends through its own mail provider and keeps what arrives from then on. Earlier mail is not fetched, and attachments are listed by name, type and size only.

Sending is two steps. mail_prepare stores the exact message and answers it with an id and a SHA-256, and sends nothing. mail_send sends that message, and only that message, when given the same id and SHA-256 within 24 hours. A message goes to at most 10 addresses, and an account sends at most 20 messages an hour and 100 a day.

Agents in chats and organizations can search, read and prepare; they cannot send. An assistant can send only on an API key or connected app you named: under Settings, API, Connectors for assistants, tick mail_send, then tick each key or app that may call it. Ticked with none named, nobody can send. Every prepared and sent message is in the activity log with who did it and the reason given.

Phone (early access)

Phone lets an AI voice agent place a call you approved and report back, in Dutch, European Portuguese or English. It is limited to n8v's own team for now and needs your own voice provider and carrier accounts. Their keys stay in your secret vault: set them under Settings, Secrets, Phone, where Check proves them with both providers without ringing anyone. n8v reads them when it calls and stores none. In Skills & MCPs, choose Connect MCP server, then Phone: pick the number calls come from, pick a voice, and confirm the name calls are placed for. Then open Line and calls and list the numbers the line may call. It dials no other number, whoever asks.

Calling is two steps. call_prepare stores the exact plan and answers it with an id and a SHA-256, and dials nothing: who is called, the opening line, what is asked, what may be agreed, how long at most and how much at most. call_place dials that plan, and only that plan, once, within 24 hours. Every call opens by saying that an AI assistant is calling, for whom, and that the call is transcribed. Calls are never recorded.

Agents in chats and organizations can prepare calls and read what came of them; they cannot dial. You place a prepared call yourself under Line and calls, after one confirmation. An assistant can place one only on an API key or connected app you named: under Settings, API, Connectors for assistants, tick call_place, then tick each key or app that may call it. A line places one call at a time, within its calls and spend a day. Stop calling pauses the line at once and ends a live call. Every prepared and placed call is in the activity log with who did it and the reason given, never with the number.

Disconnecting removes active provider tokens while preserving the connection settings. Removing a connection deletes its stored credentials and configuration.

Choose tools for each chat

Managed connections start off for every new chat. Use the plug button beside the attachment and voice actions to enable an entire MCP server or only the tools that chat needs. The selection applies only to that chat and can be changed while its agent is idle.

Configuration Format

MCP configurations use JSON format with the following structure:

{
  "mcpServers": {
    "server-name": {
      // Server configuration
    }
  }
}

Server Types

n8v supports three types of MCP servers:

1. Command-based Servers

Command-based servers run as local processes within your agent environment:

{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "your-api-key",
        "OTHER_CONFIG": "value"
      }
    }
  }
}

• command (required): The executable command to run
• args (optional): Array of command-line arguments
• env (optional): Environment variables to pass to the server

2. HTTP-based Servers

HTTP-based servers connect to remote MCP endpoints using standard HTTP requests:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

• type (required): Must be "http" for HTTP servers
• url (required): The full URL of the MCP endpoint
• headers (optional): HTTP headers to include with requests
• env (optional): Environment variables for the server

3. SSE-based Servers

SSE (Server-Sent Events) servers connect to MCP endpoints that use server-sent events for real-time communication:

{
  "mcpServers": {
    "sse-server": {
      "type": "sse",
      "url": "https://example.com/mcp-sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

• type (required): Must be "sse" for SSE servers
• url (required): The full URL of the SSE endpoint
• headers (optional): HTTP headers to include with the connection
• env (optional): Environment variables for the server

Multiple Servers

You can configure multiple MCP servers in a single configuration:

{
  "mcpServers": {
    "custom-tools": {
      "command": "python",
      "args": ["/home/user/mcp-server.py"]
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "sse-server": {
      "type": "sse",
      "url": "https://example.com/mcp-sse"
    },
    "another-server": {
      "command": "mcp-server",
      "env": {
        "CONFIG_PATH": "/etc/mcp/config.yaml"
      }
    }
  }
}

Finding MCP Servers

MCP servers can be found on the a variety of MCP server repositories. Here are some examples:

• Smithery
• Awesome MCP Servers
• Model Context Protocol servers

Sample MCP Servers

Here are some popular MCP servers you can use with n8v:

• Ref Tools - Pull in content from various sources
• Notion MCP - Integrate with Notion workspaces
• Figma MCP - Access Figma designs and resources

Repository documents

When nativeDocs is enabled for your account, doc_render reads repository documents as Markdown or sanitized HTML with resolved links. It requires files:read. Reading documents in n8v explains refs, caching and limits.