Connect Claude and ChatGPT to TaskOH

This guide shows how to let an AI assistant work in your TaskOH tasks. Every path below uses one thing: a personal access token you create on the Integrations page.

Which section do I need?

• Claude Code (terminal) → §4
• Claude Desktop app → §5
• ChatGPT (Custom GPT) → §6
• claude.ai website, Claude Desktop Connectors menu, or ChatGPT Apps/Connectors → not supported yet, see §11
• Writing your own script or app → §7

1. What it is

Your AI assistant can read, create, update, comment on and delete your tasks. It acts as you: it sees the same projects, holds the same role in each, and may do exactly what you may do in the web app. Some of its writes are recorded in the activity log — task created, status / scope / cost changes, comments and deletions (see §10 for the exact list; plain field edits such as title, assignee or labels are not logged) — in the task's Activity tab and the dashboard's Recent activity panel, with a small via API chip, so your team can tell assistant work from your own clicks.

What it is not, today:

• No OAuth sign-in. Assistants connect with a personal access token you paste into their settings (see §11 for what that rules out).
• No access to approvals, estimates, attachments or team management, and no adding or removing project members, through the assistant tools. Those stay in the web app (the assistant can still read a project's member list with get_context).

2. Before you start

A token has no permissions of its own. It acts as you, with your role in every project you belong to. Your role is per project — check it under the project's Members tab. Being the workspace owner does not by itself give you access to a project you were not added to.

Anyone can open Integrations and create tokens — owners, team members and clients alike. One token works in every workspace and project you can see; you cannot limit a token to a single project or to read-only use. Some actions are never available to a token, whatever your role: managing tokens, people, or billing, and deleting projects (§10).

Clients: the portal has no Integrations link; use https://app.taskoh.app/integrations directly (§3).

3. Create a token

1. Sign in at https://app.taskoh.app and open Integrations in the sidebar. If you use TaskOH through a client portal link (app.taskoh.app/portal/…), the portal has no sidebar — go straight to https://app.taskoh.app/integrations after signing in.

Clients: you sign in with a link we e-mail you. The button in your invitation works once and expires in 3 days; after that, choose Email me a sign-in link on the sign-in page and open the link we send (valid 15 minutes). No password is needed. If you would rather have one, set it under Account once you are signed in, or use Forgot password? on the sign-in page.

2. Click New token.
3. Fill in Name — name it after the app or machine that will use it, for example Claude Code on my laptop (up to 100 characters).
4. Choose Expires: 30 days, 90 days, 365 days (the default) or Never. Anything using an expired token stops working until you create a new one.
5. Click Create token.
6. The dialog changes to Copy your new token. Click Copy (it shows Copied), store the token in your password manager (you will paste it into the assistant in the next section), then click I've copied it. You cannot close this step with Escape or by clicking outside — copy first.

The token starts with toh_pat_ and is 72 characters long. You will not see it again: TaskOH stores only a hash and the last four characters. If you lose it, revoke it and create a new one.

Every time a token is created, TaskOH e-mails you (name, last four characters, expiry) so a token made from a hijacked browser session cannot stay hidden. You can hold at most 20 active tokens; revoke unused ones first if you hit the limit.

3.1 Find and revoke tokens later

The Personal access tokens list on the Integrations page shows each token as toh_pat_… plus its last four characters, with Created, Last used (or Never used) and Expires / Expired / No expiry. Expired tokens stay in the list until you revoke them. Last-used time updates at most once every five minutes.

To revoke: open the row's actions menu, choose Revoke…, confirm with Revoke. Anything using that token stops working immediately.

3.2 Naming advice

Create one token per assistant or machine (Claude Code on my laptop, ChatGPT team GPT, Reporting script). Then you can revoke a single one without touching the others, and the Last used column tells you which is still in use.

4. Connect Claude Code

Requires Claude Code 2.1.251 or newer. Run once in a terminal, replacing toh_pat_… with your token:

claude mcp add --transport http taskoh https://api.taskoh.app/mcp --header "Authorization: Bearer toh_pat_…" --scope user

--scope user makes TaskOH available in every project on this machine; omit it to register it for the current project only. The same command is on the Integrations page under Connect an assistant → Claude Code with a Copy button.

The command stores the token in Claude Code's user config file (~/.claude.json at the time of writing) and leaves it in your shell history. On a shared machine, delete that line from your shell's history file afterwards (~/.zsh_history on macOS, ~/.bash_history on most Linux shells), or paste the token into the config file by hand instead of typing it in the terminal.

Verify inside a Claude Code session with /mcp: taskoh is listed as connected with eight tools (get_context, get_my_tasks, search_tasks, get_task, create_task, update_task, add_comment, delete_task). Try "What's on my plate?" — Claude calls get_my_tasks.

Claude asks before running a tool that writes unless you choose Always allow — keep delete_task on ask (§9).

For a shared repository, commit a project-level .mcp.json that reads the token from an environment variable so the token never enters git:

{"mcpServers": {"taskoh": {"type": "http", "url": "https://api.taskoh.app/mcp", "headers": {"Authorization": "Bearer ${TASKOH_TOKEN}"}}}}

Then set TASKOH_TOKEN in your shell profile or a local .env that is git-ignored.

5. Connect Claude Desktop

Claude Desktop's built-in connector settings cannot hold a personal token (see §11), so use the mcp-remote bridge, which runs through Node.js.

1. Make sure Node.js is installed: open a terminal (Terminal on macOS, PowerShell on Windows) and run node --version. If it prints nothing or an error, install the LTS version from https://nodejs.org and reopen the terminal.
2. In Claude Desktop open Settings → Developer → Edit Config. This opens claude_desktop_config.json.
3. Add the taskoh entry below, replacing toh_pat_… with your token (if the file already has a mcpServers object, add the entry inside it). The same JSON is on the Integrations page under Connect an assistant → Claude Desktop.

{
  "mcpServers": {
    "taskoh": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.taskoh.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--transport",
        "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Bearer toh_pat_…"
      }
    }
  }
}

4. Save the file, then quit Claude Desktop completely (macOS: Cmd+Q; Windows: right-click the tray icon → Quit) and reopen it — closing the window is not enough, the config is only read at start. The first start downloads mcp-remote, so give it a minute before assuming the connection failed. The taskoh server should then be listed among the available tools in a new chat.

Notes:

• Keep Authorization:${AUTH_HEADER} exactly as written, with no space after the colon. The value is expanded from env, which avoids a Windows argument-quoting bug.
• --transport http-only pins the Streamable HTTP transport TaskOH speaks. Without it mcp-remote may try the legacy SSE transport, which TaskOH does not support.

6. Connect ChatGPT as a Custom GPT

Creating a GPT may require a paid ChatGPT plan; if you see no Create button, check your plan or ask your workspace admin.

1. Explore GPTs → Create (or My GPTs → Create a GPT) → Configure tab → Create new action.
2. Authentication → API Key, Auth Type: Bearer, paste toh_pat_… → Save.
3. Schema → Import from URL → https://api.taskoh.app/openapi.json → Import. Seven actions appear:

Then set Privacy policy to https://taskoh.app/privacy.html and save the GPT as Only me or Anyone at your workspace with the link.

Test it: "List my open tasks" runs without confirmation. "Create a task in Acme Portal titled 'Fix Safari login'" asks you to confirm before writing.

The three writing actions are marked consequential, so ChatGPT asks before each one. There is no delete action in the Custom GPT path.

Everyone who uses the GPT acts as the person whose token is pasted into it, and TaskOH records their events under that person's name with the via API chip. Create the token yourself, from your own account, and give the GPT its own token so revoking it disconnects every user at once. Share it only with people you would let use your account.

7. For developers

Not a developer? Skip to §8.

Everything below uses the same token. The full tool and endpoint reference — argument schemas, result shapes, error texts, name-resolution rules — is in the API & MCP reference, also served as plain text at https://api.taskoh.app/llms.txt so you can hand it to an agent.

7.1 Claude API (MCP connector)

Messages API with beta header anthropic-beta: mcp-client-2025-11-20. Pass the raw token; the API adds the Bearer scheme itself:

{"mcp_servers": [{"type": "url", "url": "https://api.taskoh.app/mcp", "name": "taskoh", "authorization_token": "toh_pat_…"}],
 "tools": [{"type": "mcp_toolset", "mcp_server_name": "taskoh"}]}

7.2 OpenAI Responses API

Headers are not stored; send them on every request:

{"tools": [{"type": "mcp", "server_label": "taskoh", "server_url": "https://api.taskoh.app/mcp",
  "headers": {"Authorization": "Bearer toh_pat_…"}, "require_approval": "never"}]}

7.3 OpenAI Agents SDK (Python)

MCPServerStreamableHttp(params={"url": "https://api.taskoh.app/mcp", "headers": {"Authorization": f"Bearer {token}"}})

7.4 curl smoke test

Check the token before configuring a client:

curl -s https://api.taskoh.app/api/dashboard/my-tasks -H "Authorization: Bearer toh_pat_…"

Expected: {"success":true,"data":[…]} with your open tasks. To check the MCP server:

curl -s -X POST https://api.taskoh.app/mcp -H "Authorization: Bearer toh_pat_…" \
  -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Expected: a JSON-RPC result listing eight tools. Any HTTP client can also call the REST endpoints in https://api.taskoh.app/openapi.json; responses use the {"success": true, "data": …} envelope.

Scripts should send a descriptive User-Agent header (for example my-script/1.0); it is good practice and identifies your client in logs. Since 2026-09-07 the API host no longer rejects Python's built-in urllib default (Python-urllib/3.x). If you ever get a plain-text 403 error code: 1010, see §12.

8. What you can ask

The assistant resolves project, member and label names for you (exact match, case does not matter) and accepts me as the assignee. Examples, with the tool the assistant will use:

8.1 Read

8.2 Create

8.3 Update

8.4 Comment

Mentions use the member's e-mail address (@maya@example.com), not their name. The assistant can look the address up with get_context for the project.

8.5 Delete

In a Custom GPT the same requests map to the seven REST actions of §6; ids come from list_projects.

9. What the assistant can and cannot do

Deleting. Permanent — the task goes with its subtasks and comments, and the tool refuses without an explicit confirm flag. Claude Code and Claude Desktop ask you before running it unless you chose Always allow — keep delete_task on ask. Assistants driven through the developer APIs in §7 do not ask unless you configure approval. Not available in the Custom GPT.

10. Security and privacy

• Storage. TaskOH stores only a SHA-256 hash of the token and its last four characters. The token itself is shown once, in the Copy your new token step, and never again — not in the list, not in the API.
• Revoke is immediate. After Revoke, the next request with that token is refused with 401 Invalid or revoked token. The same happens when a token expires.
• A token cannot manage tokens, people or billing. These always require a signed-in browser session, never a token: the Integrations page (listing, creating and revoking tokens), changing your profile or password, adding or removing project members, workspace team management, deleting a project, and Stripe checkout or billing changes. A leaked token therefore cannot mint new tokens, invite someone as a way to keep access, take over the account, or touch the subscription. It can still read and change tasks and comments in every project your role allows, so revoke it as soon as you suspect misuse. Tokens are also never shown a project's public share link.
• What is logged. Every change made with a token is an activity event under your name with via API — task created, status changed, scope changed, planned costs changed, cost sharing changed, comment added, task deleted. Other field edits (title, description, priority, due date, assignee, labels, client visibility…) are not logged. Rejected tokens are logged server-side for abuse prevention (last four characters, client IP address and path — never the token itself; see the privacy policy). Reads produce no activity events (ordinary web-server access logs still apply, see the privacy policy).
• Advice. One token per assistant or machine (§3.2). Set an expiry — 365 days is the default; use 30 or 90 for a trial. Treat the token like a password: it belongs in your password manager and in the assistant's settings — never in chats, tickets, e-mails or code repositories.
• If a token leaks: open Integrations, revoke it, create a new one for the client, and check the dashboard's Recent activity and the affected tasks' Activity tabs for events marked via API that you did not make. Since not every edit is logged (see What is logged), also look over the tasks themselves for changed titles, assignees, labels or visibility.
• Password change. Changing your password does not revoke tokens. Revoke them yourself if you suspect misuse.

11. Not available yet

TaskOH does not offer OAuth sign-in yet. Any client that connects only through an OAuth flow cannot connect today:

• claude.ai and Claude Desktop native connectors (Settings → Connectors → Add custom connector). Adding https://api.taskoh.app/mcp there fails to connect. Use Claude Code (§4) or Claude Desktop with mcp-remote (§5).
• ChatGPT developer-mode connectors (Settings → Apps, Authentication: OAuth). Use a Custom GPT (§6).

OAuth is on the roadmap; personal access tokens will remain supported.

One exception: some claude.ai organizations already see a beta Request headers section in the custom-connector dialog. If yours does, set Authentication to None and add a header named authorization with the value Bearer toh_pat_…. Caveats: the feature is labelled beta and limited to some organizations, the header is sometimes not sent, and the credential is shared by everyone in your organization — use a dedicated token and revoke it when the OAuth path arrives.

12. Troubleshooting

13. FAQ

Does the assistant provider see my TaskOH data?
Yes — whatever the assistant reads is sent to the AI provider (Anthropic, OpenAI) as part of the conversation. Create tokens only for assistants your workspace allows.

Can I give an assistant read-only access, or access to one project only?
No. A token acts as you everywhere. If you need a narrower view, create a separate TaskOH user with the right memberships and make the token there.

Can my client use an assistant too?
Yes. Clients can create tokens; their assistant sees only client-visible tasks, can create requests and comment, and cannot update or delete tasks.

Will the assistant create labels, projects or members?
No. Labels must already exist in the project; unknown names are rejected. Projects and members are managed in the web app.

Does deleting through an assistant leave a trace?
Yes. A Task deleted event with the task's title stays in the dashboard's Recent activity even though the task is gone, marked via API.

How many requests can an assistant make?
120 requests per minute per token, counted across everything the token does (the assistant tools and the REST endpoints together). Above that TaskOH answers 429 Too Many Requests and the assistant has to wait 60 seconds (the Retry-After header) before trying again; the token itself keeps working. The limit is per token, not per network address, so your other tokens are unaffected and several people behind one IP address (for example hosted assistants) do not slow each other down. Assistants that send several commands in one message use up one request per command. The web app is not limited, except that it uses the same allowance when it talks to the assistant endpoint. Result sizes are capped: up to 100 tasks per list, up to 100 per page when searching a project, 50 comments and 50 activity events per task.

What happens when my token expires?
The client gets 401 Invalid or revoked token. The token stays in your list marked Expired until you revoke it; create a new one and update the client.

Which tokens do I have and are they in use?
See the Personal access tokens list on Integrations (§3.1).