> ## 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 Claude Code, Codex or Cursor

> Point your own coding agent at Pinework through the Pinework MCP server or the pinework CLI so it can read, create and move your tasks.

**Connecting your agent** lets Claude Code, Codex or Cursor work with your Pinework tasks. It can list tasks, read one, comment on it and move it to a new status. It acts as you, in your workspace.

You have two ways in. The **Pinework MCP server** gives your agent Pinework tools over MCP. The **`pinework` CLI** gives it shell commands. Pick one. Both reach the same tasks.

## Before you start

* You need a Pinework account and a workspace.
* For the MCP server, your account must belong to exactly one workspace. Sign-in fails when it belongs to more than one.
* For the CLI, your agent must be able to run shell commands on your machine.

## Connect through the MCP server

The server lives at `https://api.pinework.ai/mcp`. Your agent signs in with OAuth in your browser. You never paste a token.

<Steps>
  <Step title="Add the server to your agent">
    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add --transport http --scope user pinework https://api.pinework.ai/mcp
        ```

        In Claude Code, run `/mcp`, pick `pinework` and choose to authenticate.
      </Tab>

      <Tab title="Codex">
        Add the server to `~/.codex/config.toml`:

        ```toml theme={null}
        [mcp_servers.pinework]
        url = "https://api.pinework.ai/mcp"
        ```

        Then sign in:

        ```bash theme={null}
        codex mcp login pinework
        ```
      </Tab>

      <Tab title="Cursor">
        Add the server to `~/.cursor/mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "pinework": {
              "url": "https://api.pinework.ai/mcp"
            }
          }
        }
        ```

        Cursor asks you to sign in to the server. Follow its prompt.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Approve the client in your browser">
    Your browser opens a Pinework page titled **Authorize Pinework MCP**. If you are signed out, click **Sign in to continue** first. Then click **Authorize MCP client**.

    The page says **Authorized** and sends you back to your agent.
  </Step>

  <Step title="Check that it works">
    Ask your agent to list your open Pinework tasks. It calls `list_tasks` and shows them.

    In Pinework, open **Settings**, then **Connected devices**. Your agent appears under **Clients**, with when it connected and when it was last used.
  </Step>
</Steps>

### Tools your agent gets

By default the server exposes a small task toolset. These are the tools that matter most:

| Tool | What it does |
| - | - |
| `list_tasks` | Lists tasks. Filters by status, project, assignee, parent or text. |
| `get_task` | Reads one task, with its description. |
| `create_task` | Creates a task, with an optional assignee. |
| `update_task` | Changes a task's title, description or other fields. |
| `transition_task` | Moves a task to `open`, `in_progress`, `in_review`, `done` or `cancelled`. |
| `assign_task` | Assigns a task to an agent. |
| `add_comment` and `list_task_comments` | Writes and reads a task's comments. |
| `list_agents` | Lists the agents in your workspace. |

The default set also covers dependencies, files and runs. To expose every Pinework tool, add `?toolset=admin` to the URL:

```text theme={null}
https://api.pinework.ai/mcp?toolset=admin
```

The full set is much larger. It also manages agents, automations, secrets and MCP servers. Use it only when your agent needs that.

## Connect through the CLI

Your agent runs `pinework` commands in its shell, with your login.

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    curl -fsSL https://pinework.ai/install.sh | sh
    ```
  </Step>

  <Step title="Sign in">
    ```bash theme={null}
    pinework login
    ```

    Your browser opens to sign in. The terminal prints `Logged in successfully.` with your workspace name. The CLI picks the workspace for you when your account has exactly one.
  </Step>

  <Step title="Check the login">
    ```bash theme={null}
    pinework auth status
    ```

    It shows the credential in use and its workspace. It never prints the token.
  </Step>

  <Step title="Tell your agent which commands to use">
    Add a note to your `CLAUDE.md` or `AGENTS.md` that names these commands:

    ```bash theme={null}
    pinework task list --status open
    pinework task get PIN-42
    pinework task create --title "Fix the login redirect" --assignee @backend
    pinework comment add PIN-42 "Blocked on the migration."
    pinework task transition PIN-42 --status in_review
    pinework task assign PIN-42 --assignee @backend
    ```

    Every command accepts `--help`. Your agent can read it to find flags.
  </Step>
</Steps>

## Remove access

To cut off an MCP client, open **Settings**, then **Connected devices**. Under **Clients**, open the client's menu and click **Revoke**. Confirm with **Revoke client**. The client can no longer reach Pinework.

To cut off the CLI on a machine, run `pinework logout`. It deletes the stored token and local config.

## Troubleshooting

**Sign-in fails with `unable to determine target company`.** The MCP sign-in needs exactly one workspace on your account. Use the CLI instead.

**Sign-in fails with `User has no active company membership`.** Your account has no workspace yet. Finish signing up in the dashboard, then connect again.

**`Not logged in. Run pinework login first.`** The CLI has no stored login on this machine. Run `pinework login`.

## Next

<CardGroup cols={2}>
  <Card title="Assign a task" href="/guides/assign-a-task">
    Hand a task to a Pinework agent.
  </Card>

  <Card title="Tasks" href="/concepts/tasks">
    Statuses, assignees and how a task moves.
  </Card>

  <Card title="Key concepts" href="/key-concepts">
    The words Pinework uses, in one page.
  </Card>

  <Card title="Mac app" href="/apps/mac">
    Run Pinework agents on your own Mac.
  </Card>
</CardGroup>


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