Connect your AI to PUDL

Connect your AI client once for a workspace. It can find things you saved even when you forget which pool they're in.

https://pudl.ai/mcp

There is no PUDL software to install for remote access. You can also browse Your pools yourself.

1. Let your agent set up the connection

Give it this instruction. Keep your existing client settings and accounts.

Use my existing PUDL connection for this workspace if available. Otherwise connect this client to https://pudl.ai/mcp using https://pudl.ai/quickstart. Request pudl:read and pudl:data:write with scoped-agent/v1 and let me review access. Preserve my other settings. Search my pooled contributions by topic when I don't name a pool. Save only when my task calls for it and only with contribution permission.

Codex setup

Add this entry to ~/.codex/config.toml, keeping other settings. Use a different server name if pudl already exists.

[mcp_servers.pudl]
url = "https://pudl.ai/mcp"
scopes = ["pudl:read", "pudl:data:write"]

Then start sign-in with the explicit scopes:

codex mcp login pudl --scopes pudl:read,pudl:data:write

Claude Code setup

To make PUDL available across your projects on this computer, use user scope. If a project must be isolated, configure only its restricted connection there instead. Keep existing entries.

In Bash, Zsh or PowerShell 7.3+ with standard argument handling (Claude Code 2.1.196+):

claude mcp add-json --scope user pudl '{"type":"http","url":"https://pudl.ai/mcp","oauth":{"scopes":"pudl:read pudl:data:write"}}'

The quickstart also covers Windows PowerShell 5.1 and connecting just one project.

Use an interactive terminal:

claude mcp login pudl

Other clients need Streamable HTTP MCP with OAuth and explicit scopes or profile support. See the full quickstart for client alternatives and recovery.

2. Sign in and choose access

Keep the client running while you sign in. For a new connection, the default is all pools you can access in this workspace, now and later. That includes pools shared with you while you have access. Choose Limit access if this client should only use specific pools.

For read-only access, clear Save contributions and leave management actions off. Review your choices, then select Allow.

Starting with an empty workspace?

To let your agent create your first pool, allow Create private pools. Direct workspace owners/admins can also allow Join pools for eligible pools. To save data, also allow contributions. Create and join permissions start unchecked.

Direct workspace owners/admins can also create the first private pool on the consent page. To join someone else's private pool, use their invitation and approval process.

3. Use your pools in chat

On iPhone, use Share → PUDL to save a link titled “Camera tutorial.” In chat, ask “Find the camera tutorial I saved from my phone.” Your agent can search saved titles and content across its pools with read access.

You can also say “Use Launch for this chat.” Your agent can ask which pool you meant before saving if several destinations match.

Connect a second client independently if you want both agents to work in the same pool. You can revoke each from Your account.

Use existing sources

Use this optional setup when you want this client to use tools from sources already connected to your pool. Keep the data-only setup above for reading and saving data.

Connect this client to https://pudl.ai/mcp with scoped-agent/v1 and request pudl:read, pudl:connections and pudl:invoke. Keep pudl:data:write only if I also want to save data. Complete normal PUDL sign-in and let me review the workspace, pool coverage and tool-use permission. If this client already has data-only access, use its normal reconnection flow to request the additional permissions; do not copy or create tokens yourself. Discover existing sources with connections. Reuse the configured connection after its authorized manager approves this exact agent and selected tools. Do not ask for provider keys in chat or create another provider connection just because this is a new AI client.

Consent lets the client request approved tools. The source manager separately approves which tools this exact agent may use. A new client can reuse an existing business or personal connection without entering the provider key again. Existing clients keep their current permissions until you explicitly change them.

Manage sources from your workspace's Hosted connections page. Provider keys are entered only in that private browser form. Each source and credential choice has its own permissions; seeing a source or reading its pool does not grant tool use.

Remote access needs no PUDL checkout, Node.js, Docker, gateway, administrator permission or provider key on your computer. Agent instructions · Your pools