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

# Connect an outside service

> Sign in to a marketplace service once so your agents use its tools while Pinework keeps the token.

A **connection** is your signed-in link to an outside service, such as Linear, Notion or HubSpot. You sign in once. Pinework stores the token, and your agents use the service's tools in their runs.

The service's catalog entry decides how you sign in. Most use OAuth in a popup. Some ask for an API key. A few need no sign-in at all.

## Before you start

* You need a Pinework account and a workspace. An agent cannot create a connection. Only a signed-in person can.
* Have an account at the outside service. For an API key service, create the key there first.
* For the CLI tab, install the `pinework` CLI and run `pinework login`.

To connect GitHub for repos and pull requests, follow [Connect GitHub](/guides/connect-github) instead.

## Connect the service

<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="Pick the service">
        Click **Add MCP server**. In the **Add an MCP server** dialog, type in **Search the marketplace**. Each row shows how it signs in: **OAuth**, **API key**, **Optional API key** or **No sign-in**.

        Click the service. A dialog titled **Connect** and the service's name opens.
      </Step>

      <Step title="Sign in">
        Click **Connect** followed by the service's name.

        For an OAuth service, a popup opens at the service's sign-in page. The dialog says `Waiting for you to approve access in the popup...`. Approve access in the popup.

        For an API key service, the dialog shows one field per value the service needs. Paste the values and click **Save and connect**.

        For an optional key service, pick **Connect (free)** or **Connect with API key**.
      </Step>

      <Step title="Check the result">
        A toast says `Connected to <service>`. The service appears in the **MCP Servers** list. A service already in the list shows **Added** in the marketplace.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Start the connection">
        Pass the service's catalog id, such as `linear`. The CLI requires `--owner-type`.

        ```bash theme={null}
        pinework connection create --integration-id linear --owner-type company
        ```

        For an API key service, pass the values as JSON:

        ```bash theme={null}
        pinework connection create --integration-id gitlab --owner-type company \
          --api-key-fields '{"api_key":"<your token>"}'
        ```
      </Step>

      <Step title="Finish an OAuth sign-in in your browser">
        The command prints a setup result. For an OAuth service, `status` is `human_required`. Open the URL in `nextStep.authorizeUrl` in your browser and approve access. The browser shows **Connection complete**.

        For an API key service, or a service with no sign-in, `status` is already `connected`.
      </Step>

      <Step title="Check the result">
        ```bash theme={null}
        pinework connection list --status active
        ```

        The list shows the connection with its `conn_` id.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## How your agents use it without the token

Pinework keeps the token or key in its own store. How the token reaches the service depends on where the run happens.

* **In a cloud run**, Pinework adds the token to requests bound for that service as they leave the sandbox. The agent never reads the token. A service Pinework cannot handle this way is left out of cloud runs.
* **On your own device**, Pinework hands the token to the service's tool settings when the run starts. The token is on your machine for that run.

Pinework refreshes an OAuth token when the service allows it. See [Cloud and device](/concepts/cloud-and-device) for where runs happen.

<Note>
  A connection belongs to the person who signed in. Only agents you created, and agents they created, use your connection. An agent another person created runs without this service's tools.
</Note>

## Reconnect or remove a connection

A connection row shows a state when it needs you. **Setup incomplete** means a sign-in started and never finished. **Revoked** means access was withdrawn. Pinework leaves a connection out of runs until it is active again.

<Tabs>
  <Tab title="Dashboard">
    Click the row to open it. The dialog shows **Source**, **Sign-in**, **State** and **Added**.

    * To sign in again, click **Finish setup**. It shows on any connection that is not active. The sign-in dialog opens again.
    * The row of such a connection also has a **Reconnect** button. It opens the same sign-in dialog.
    * To stop using the service, click **Remove**. Pinework revokes the connection.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Sign in again to an expired or revoked connection
    pinework connection reauthorize conn_123

    # Stop using the service
    pinework connection revoke conn_123
    ```

    `reauthorize` works on an `expired`, `revoked` or `pending` connection, and on an active OAuth connection whose token has expired. A `pending` connection gets its open sign-in back. It prints a setup result with an `authorizeUrl` for an OAuth service.
  </Tab>
</Tabs>

## Troubleshooting

**The popup did not open.** Your browser blocked it. Click **Re-open authorization window** in the dialog.

**`Authorization window was closed before completing. Try again.`** You closed the popup before you approved access. Click **Try again**.

**`That API key didn't work. Double-check it and try again.`** The service refused the key. Click **Try again** and paste a fresh key.

**An agent's run has no tools from the service.** Check that the connection is active. Then check that you created the agent.

## Next

<CardGroup cols={2}>
  <Card title="Add an MCP server" href="/guides/add-an-mcp-server">
    Add a server that is not in the marketplace.
  </Card>

  <Card title="Secrets" href="/concepts/secrets">
    How Pinework stores keys and passwords for your agents.
  </Card>

  <Card title="Cloud and device" href="/concepts/cloud-and-device">
    Where runs happen and what each place can reach.
  </Card>

  <Card title="Connect GitHub" href="/guides/connect-github">
    Give agents your repos and pull requests.
  </Card>
</CardGroup>


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