Connect Walnut to Claude, ChatGPT, or Codex with the Walnut MCP

The Walnut MCP connects your Walnut account to your AI assistant, so you can ask plain-language questions about your workspace and get answers from your live Walnut data. You don't need dashboards or exports.

It works with Claude, ChatGPT, and Codex. Setup takes about a minute in any of them.

Before you start

• You need Claude, ChatGPT, or the Codex app, signed in to your account.
• You need a Walnut account. You approve the connection with your Walnut login.
• The Walnut MCP server URL is https://api.teamwalnut.com/mcp. You sign in with your Walnut account, so there's no API key to paste.

If you're using a business- or company-owned account, only the account owner can add custom connectors for you to use. Please ask them to add them first; then, after a few minutes, you'll see the app in your connectors list, and all you should do is "authenticate"

Connect in Claude

1. Open the Claude desktop app and go to the main page.

2. In the message box, click the + button.

3. Hover over Connectors and click Browse connectors.

   

4. In the Directory, click the "browse connection" and then click the "+ADD" to add a custom connector for Walnut MCP

5. In the opened panel, you should add the MCP's URL https://api.teamwalnut.com/mcp and click 'connect'.

6. A browser tab opens and asks you to finish connecting. Click Continue connecting.

7. On the Walnut approval screen, choose an Access level:

   • Full access: Claude can read your data and make changes, such as renaming or archiving items.
   • Read-only: Claude can read your data but can't change anything.

8. When you see Connected, return to the app. You can close the browser tab.

9. Click + > Connectors again and make sure the Walnut MCP toggle is on.

   

That's it. Claude shows Connected to Walnut MCP when the connection succeeds.

Connect in ChatGPT

Add the Walnut MCP to ChatGPT as a custom connector using the server URL https://api.teamwalnut.com/mcp. When ChatGPT asks you to sign in, a browser tab opens the Walnut approval screen. Choose Full access or Read-only, then click Authorize.

Connect in Codex

1. Open the Codex app and go to Settings > Plugins.

2. Open the MCPs tab, click Add, and choose to connect a custom MCP.

3. Fill in the form:

   • Name: walnut_mcp
   • Type: Streamable HTTP
   • URL: https://api.teamwalnut.com/mcp

   Leave Bearer token env var, Headers, and Headers from environment variables empty. You sign in with your Walnut account instead, so there's no token or API key to add.

4. Click Save.

5. Back in the MCPs tab, find walnut_mcp under Servers and click Authenticate.

6. A browser tab opens with Codex wants to access your Walnut account. Choose an Access level:

   • Full access: Codex can read your data and make changes, such as renaming or archiving items.
   • Read-only: Codex can read your data but can't change anything.

   Check the list of resources and permissions Codex will get, then click Authorize.

7. Return to the Codex app. You can close the browser tab.

8. Make sure the walnut_mcp toggle is on.

Ask your first question

Type a question in the message box, for example "How many users do we have in our Walnut account?"

Your assistant uses the Walnut MCP to look up the answer. In Claude, you'll see Used Walnut MCP integration above the reply.

The Walnut MCP works with the same permissions you have in Walnut. Your assistant only sees, and only changes, what you can access yourself.

Troubleshooting

I don't see Walnut MCP when I search the Claude Directory. Your Claude workspace may need an admin to make the connector available. Ask your Claude admin, or contact your Walnut account team.

My assistant doesn't use Walnut to answer my question. In Claude, click + > Connectors and check that the Walnut MCP toggle is on. The connector can be connected but switched off for a conversation. In Codex, go to Settings > Plugins > MCPs and check that the walnut_mcp toggle is on.

Codex won't connect. Check that the URL is exactly https://api.teamwalnut.com/mcp and the type is Streamable HTTP, then click Authenticate again. To change the server type, Codex asks you to uninstall the server first: open walnut_mcp, click Uninstall, and add it again.

My assistant says it can't make a change. You may have connected with Read-only access, or the change may need an Account owner or Company admin. To switch to Full access, reconnect: in Claude, disconnect Walnut MCP in Manage connectors and connect again; in Codex, uninstall walnut_mcp and add it again.

I closed the approval screen by mistake. Start the connection steps again. Connecting a second time is safe.

What you can do

Anyone in your Walnut account can ask about:

• Demo analytics: sessions, completions, bounces, and top Demos
• Users and activity: who's in your account, their role, and when they last signed in
• Seats and licenses: how many Editor, Presenter, and Viewer seats are used and left

Library organization and member management (for Account owners and Company admins) are rolling out now.

See What you can do with the Walnut MCP for the full list, including which capabilities need an admin role.

Share your feedback

We're building out the Walnut MCP and want to hear what worked, what didn't, and what you'd like it to answer next. Contact your Walnut account team or reach out to support.