> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinework.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an MCP server

> Add an MCP server to your workspace, sign in to it if it asks, and turn it on or off for each agent.

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](/guides/add-a-connection).

## 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](/concepts/secrets) 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

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open the MCP Servers tab">
        In the sidebar, click **Customize**. Then click the **MCP Servers** tab.
      </Step>

      <Step title="Start a custom server">
        Click **Add MCP server**. In the **Add an MCP server** dialog, under **Your own**, pick **Add custom MCP server**.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Save it">
        Click **Add server**. A toast says `Added <name>`. The server appears in the list with its transport and host.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Create the server">
        A remote server needs `--url`. A stdio server needs `--command`. Pass `--args` once per argument.

        ```bash theme={null}
        # 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.
      </Step>

      <Step title="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.

        ```bash theme={null}
        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`.
      </Step>

      <Step title="Check it">
        Run `pinework mcp list`. The list prints every workspace server. An auth-state summary prints on stderr.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Sign in to the server

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.

<Steps>
  <Step title="Click Connect">
    On the **MCP Servers** tab, click **Connect** on the server's row. You can also open the server and click **Connect** there.
  </Step>

  <Step title="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.`
  </Step>

  <Step title="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**.
  </Step>
</Steps>

<Note>
  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.
</Note>

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.

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open the agent">
        In the sidebar, click **Agents**, then click the agent. The **Configure** view opens.
      </Step>

      <Step title="Find the server">
        Scroll to the **Tools** section. Click the **MCP Servers** tab.
      </Step>

      <Step title="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>`.
      </Step>

      <Step title="Undo the override">
        To follow the workspace setting again, open **More actions** and click **Reset to workspace**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

## 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.

## Next

<CardGroup cols={2}>
  <Card title="Connect an outside service" href="/guides/add-a-connection">
    Pick a service from the marketplace and sign in once.
  </Card>

  <Card title="Import your setup" href="/guides/import">
    Bring MCP servers over from Claude Code, Codex, Cursor or OpenCode.
  </Card>

  <Card title="Secrets" href="/concepts/secrets">
    How Pinework stores the keys your servers use.
  </Card>

  <Card title="Plugins and skills" href="/concepts/plugins-and-skills">
    How a plugin brings its own MCP servers.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.