Add an MCP server

An MCP server gives your agents tools from another system, such as a database, a browser or an issue tracker. You add it once to the workspace. When it is ready, every agent gets its tools on its next run. You can turn it off for one agent. This page covers a server you add by URL or command. To pick a service from the marketplace, see Connect an outside service.

Before you start

You need a Pinework account and a workspace. An agent cannot add an MCP server. Only a signed-in person can.
For the CLI tab, install the pinework CLI and run pinework login.
Know how the server runs. A remote server has an https:// URL. A local server starts from a command, such as npx.
If the server needs an API key, save the key as a secret first. Pinework rejects a value that looks like a raw key. This covers the URL, headers, arguments and KEY=value pairs.

Add the server to your workspace

Dashboard
CLI

Open the MCP Servers tab

In the sidebar, click Customize. Then click the MCP Servers tab.

Start a custom server

Click Add MCP server. In the Add an MCP server dialog, under Your own, pick Add custom MCP server.

Fill in the form

Enter a Name. Pick a Transport: HTTP, SSE or stdio.For HTTP or SSE, enter the URL. Add any headers in the Headers, one Name: value per line box. Set Sign-in to OAuth if the server asks you to sign in. Otherwise leave it on None.For stdio, enter the Command and the Arguments, one per line. Add any variables in the Environment, one KEY=value per line box.

Save it

Click Add server. A toast says Added <name>. The server appears in the list with its transport and host.

Create the server

A remote server needs --url. A stdio server needs --command. Pass --args once per argument.

# A remote server that uses OAuth sign-in
pinework mcp create --name linear-tools --type http \
  --url https://mcp.example.com/mcp --auth-kind oauth

# A local stdio server
pinework mcp create --name everything --type stdio \
  --command npx --args -y --args @modelcontextprotocol/server-everything

The command prints the new server with its mcp_ id.

Attach an API key, if the server needs one

Point the server at a saved secret with --secret-ref vault:<name>. For HTTP and SSE, Pinework sends it in the Authorization header as a bearer token. Use --header-name to send it in another header.

pinework mcp create --name search --type http \
  --url https://mcp.example.com/mcp \
  --auth-kind api_key --secret-ref vault:search-key

Set at most one of --secret-ref or --connection-id.

Check it

Run pinework mcp list. The list prints every workspace server. An auth-state summary prints on stderr.

A server set to OAuth shows Not connected until you sign in. A remote server with no sign-in shows Not checked until Pinework checks what it needs. Pinework leaves a server out of every run while it waits for a sign-in or a key. The run still starts without that server.

Click Connect

On the MCP Servers tab, click Connect on the server’s row. You can also open the server and click Connect there.

Finish the sign-in in the new tab

A new tab opens the service’s own sign-in page. A toast says Finish the sign-in in the new tab, then turn the server on.

Check the server is on

Back in Pinework, Not connected is gone from the row. A server that is ready shows no state word. Open the row’s More actions menu. If it offers Enable, the server is off. Click Enable.

The sign-in belongs to you. Only agents you created, and agents they created, use your sign-in. An agent another person created runs without this server.

A stdio server cannot use OAuth. It reads its credentials from its KEY=value pairs or from a --secret-ref secret.

Turn the server on or off for one agent

A workspace server is on for every agent by default. You can override that for one agent.

Dashboard
CLI

Open the agent

In the sidebar, click Agents, then click the agent. The Configure view opens.

Find the server

Scroll to the Tools section. Click the MCP Servers tab.

Turn it off or on

Open the server row’s More actions menu. Click Disable or Enable. A toast says <name> disabled for <agent> or <name> enabled for <agent>.

Undo the override

To follow the workspace setting again, open More actions and click Reset to workspace.

# Turn one server off for one agent
pinework mcp set-agent-override mcp_123 --agent agt_456 --enabled false

# See which servers are on for that agent, and why
pinework mcp agent-overrides --agent agt_456

# Follow the workspace default again
pinework mcp clear-agent-override mcp_123 --agent agt_456

Change or remove a server

To change a server, run pinework mcp update <mcp_…> with the flags you want to change. The transport type cannot change. To turn a server off for the whole workspace, open its More actions menu on the MCP Servers tab. Click Disable. Or run pinework mcp update <mcp_…> --enabled false. To delete it, open More actions and click Remove. Or run pinework mcp delete <mcp_…>.

Troubleshooting

Raw credentials must not be inlined. A header, URL, argument or KEY=value pair looks like a key. Save the key as a secret. Then use --secret-ref vault:<name>, or put vault:<name> in the value. An MCP server named "<name>" already exists. Names are unique in a workspace. Pick another name. The name pinework is reserved too. The server shows Needs a key. It is set to API key auth with no secret. Run pinework mcp update <mcp_…> --secret-ref vault:<name>. This server already authenticates with an API key. Connect only works on a server with no secret. Clear the secret first, or keep using the key. The sign-in tab says Redirect URI not allowed. Some services, such as Mintlify, accept only callback URLs an admin allows. Ask an admin of that service to allow https://api.pinework.ai/api/v1/connections/callback, then click Connect again. An agent’s run has no tools from the server. Check three things. The server’s row shows no state word, such as Not connected or Needs a key. The server is on for that agent in its Tools section. For an OAuth server, you created the agent.

Connect an outside service

Pick a service from the marketplace and sign in once.

Import your setup

Bring MCP servers over from Claude Code, Codex, Cursor or OpenCode.

Secrets

How Pinework stores the keys your servers use.

Plugins and skills

How a plugin brings its own MCP servers.

Get started

Hand work to agents

Set up an agent

Work on your code

Automate repeat work

Drive Pinework from your agent

Work from the apps

Understand Pinework

Add an MCP server

Before you start

Add the server to your workspace

Turn the server on or off for one agent

Change or remove a server

Troubleshooting

Next

Connect an outside service

Import your setup

Secrets

Plugins and skills

​Before you start

​Add the server to your workspace

​Sign in to the server

​Turn the server on or off for one agent

​Change or remove a server

​Troubleshooting

​Next

Connect an outside service

Import your setup

Secrets

Plugins and skills

Before you start

Add the server to your workspace

Sign in to the server

Turn the server on or off for one agent

Change or remove a server

Troubleshooting

Next