MCP Servers

MCP (Model Context Protocol) is a standard way for a service to expose its own tools to an AI. Connect one to a project and the agent stops guessing at someone else’s API: it asks the server what it can do, then calls it.

Typical uses: pull a ticket’s details out of Linear before building the page it describes, read structured content from a CMS, or query an internal service that knows your product’s data.

Servers are set up per project. Once one is connected, the agent can use it in any chat for that project. There’s nothing to switch on in chat.

What Plyed supports

• HTTP MCP servers only. You give Plyed the server’s URL. Servers that run as a local command are not supported.
• Public internet only. The URL has to resolve to a public address. A server running on your own Mac (http://localhost:3000, http://127.0.0.1:…) is refused. So is anything on a private network address, even when a hostname points at one.
• Chats on your Mac. MCP servers are used by the AI Chat running on your computer. Cloud agents can’t reach them.
• Figma is separate. Plyed has its own Figma integration and doesn’t use MCP servers for it. See Build from Figma.

Add a server

1. Open AI Chat and switch the chat sidebar to the Tools tab.

2. Pick MCP.

3. Click New server and give it a name. The name is how you’ll refer to the server in chat, for example linear.

4. Fill in the form:

   Field	What goes in it
   Name	What you call it in chat
   URL	The server’s https://… address
   Enabled	When it’s off, the AI can’t call the server
   Sign-in	API key or Browser sign-in, depending on the server (see below)
   Headers	Extra request headers, one Name: value per line. Most servers need none.

Each field saves when you leave it.

Note

Each server is saved as a small file in your project, under .plyed/mcp/. It travels with the project: it’s included when you back up to GitHub, and anyone who opens the project gets the server too. Your key or sign-in never goes in that file (see below).

Sign in to the server

Check the server’s own documentation to see which kind of sign-in it uses, then pick the matching option under Sign-in.

API key

1. Choose API key.
2. Paste your key into the API key field and click Save key (or press Enter).

The key is kept for your account on this computer. The project file only gets a placeholder that points to it, so the key is never committed or shared. The hint under the field shows whether a key is saved.

To change the key, paste a new one and save it again. Remove key deletes it from this computer.

Because the key stays on your computer, a teammate who opens the same project has to paste their own key before the server works for them.

Browser sign-in

1. Choose Browser sign-in.
2. Click Connect. The service’s own sign-in page opens in your web browser.
3. Approve access there. The panel updates by itself once it’s done. It shows Waiting for your browser… while you finish.

You don’t paste anything, and the sign-in is kept for your account on this computer. To remove access, click Disconnect.

Don’t paste keys into Headers

The Headers box is saved into the project file, so a key typed there ends up in your repository. Always use the API key field. If you edit headers by hand, only placeholders that start with ${PLYY_MCP_ are filled in. Anything else, like ${API_KEY}, is sent as that literal text, and the server will reject it.

Check it works

Ask in chat, in plain language:

List my MCP servers.

You’ll get each server’s name, whether it’s enabled, and its URL. Then:

What tools does linear expose?

This makes the agent connect and ask the server for its tool list. It’s the first real proof that the URL and your sign-in are right. After that, just describe the task and the agent picks the right tool itself.

To point the agent at one server explicitly, right-click it in the list and choose Reference in chat.

Note

The agent treats whatever an MCP server sends back as information, not as instructions. If a server’s response tells the agent to change your files or publish your site, the agent ignores it.

Turn a server off or delete it

Untick the checkbox next to a server in the list (or Enabled in the form). The agent can’t call a disabled server at all, which helps when a service is down and you don’t want the agent to keep retrying.

Right-click a server for Enable/Disable, Reference in chat and Delete. Deleting a server doesn’t delete its saved key, because other projects may use a server with the same name. Remove the key first with Remove key if you no longer need it.

Troubleshooting

Errors show up in chat and name the server, like Error: MCP server "linear" — ….

What you see	What it means
"localhost" is a local address — MCP servers may only reach the public internet.	The URL points at your own computer. Only public addresses are allowed.
is a private or reserved address / resolves to a private or reserved address	Same rule, reached through a hostname or a redirect that leads to a private address.
MCP servers must use http(s) URLs.	The URL doesn’t start with http:// or https://.
MCP server has no URL yet	The server exists but its URL field is empty.
could not resolve "…" — check the URL.	The hostname has a typo, or the host no longer exists.
MCP server "x" is disabled.	Turn Enabled back on.
unknown MCP server "x". Configured: …	The name you used in chat doesn’t match a server. The real names are listed after the message.
The agent says a server needs you to click Connect	The server uses Browser sign-in and isn’t connected on this computer yet. Click Connect in the server’s form. The agent can’t sign in for you.
MCP 401: / MCP 403:	Sign-in failed. For API key, check the hint under the field says a key is saved, and paste it again if it’s expired. For Browser sign-in, click Disconnect and then Connect again.
MCP error -32602: … (or another number)	The server itself refused the request. The text after the number is the server’s own explanation.
MCP server "x" advertised no tools.	Plyed connected, but the server offers no tools. This often means the URL points at the wrong address on that service.
refusing cross-origin redirect … / is not method-preserving	The URL redirects somewhere else. Use the final address instead.

If the server sends back images, the agent doesn’t see them. It only gets a note saying how many images were left out.