AI Connectors
Connect Codex to Gravitask
Codex connects to Gravitask over streamable HTTP with an API key, and the CLI, the IDE extension and the Codex desktop app all read one config.toml, so you set it up once. The one thing people get wrong: bearer_token_env_var takes the NAME of an environment variable, never the key itself.
1. Create an API key
In the Gravitask app, open Settings > API & MCP and generate a key (create a free account first if you need one; API access needs Pro or higher). Grant the least access that does the job: pick the Read only scope for analysis and reporting, or restrict the key to tool groups such as Time tracking. The decision guide explains the options. Copy the key now; it is shown once.
2. Add the server to Codex
There are two ways in, and they end at the same configuration. Pick whichever matches how you use Codex.
In the terminal (CLI)
Set your API key in an environment variable, then point Codex at that variable name. Do not put the token value in the bearer token env var field.
Configured with the codex CLI; the entry is written to ~/.codex/config.toml.
export GRAVITASK_API_KEY="YOUR_API_KEY"
codex mcp add gravitask --url "https://app.gravitask.com/mcp" --bearer-token-env-var GRAVITASK_API_KEYIn the GUI: IDE extension and the Codex app
The Codex IDE extension (VS Code, Cursor and Windsurf) and the Codex desktop app read the same ~/.codex/config.toml as the CLI, so a server added on either side appears everywhere. To set it up from the extension, open the gear menu > MCP settings > Open config.toml, paste the block below, then start a new Codex session. In the Codex app, open the MCP section of the settings and add the server there. Codex cloud tasks on the web cannot use custom MCP servers, so connect through the CLI, the extension, or the app.
~/.codex/config.toml, shared by the CLI, the IDE extension, and the Codex app.
IDE extension: gear menu > MCP settings. Codex app: type /mcp to see server status.
# ~/.codex/config.toml
[mcp_servers.gravitask]
url = "https://app.gravitask.com/mcp"
bearer_token_env_var = "GRAVITASK_API_KEY"
enabled = true3. Check it works
- Run codex mcp list and check gravitask appears with the URL https://app.gravitask.com/mcp.
- Start codex and ask: "What Gravitask projects can you see?" A project list means the connection works.
- In the IDE extension or the Codex app, start a new session and ask the same question: both read the config.toml the CLI wrote. In the app you can also type /mcp to see server status.
Prompts to try
- “Summarise the open work in my Gravitask Mobile project.”
- “Create a Gravitask task for every failing test in this run, tagged bug.”
- “What is on my plate today across all Gravitask projects?”
Troubleshooting
“Codex does not show Gravitask tools”
Check the URL is exactly https://app.gravitask.com/mcp and that bearer_token_env_var contains an environment variable NAME such as GRAVITASK_API_KEY. The token value itself belongs in that environment variable, exported before Codex starts.
“Works in the CLI but not in the IDE extension or the app”
Codex launches MCP servers when a session starts, so reload the IDE window (or start a new Codex session) after editing config.toml. If it still fails, the app cannot see GRAVITASK_API_KEY: apps launched from the Dock do not read your shell profile. Launch the IDE from a terminal, or swap bearer_token_env_var for http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }, remembering the key is then stored in plain text.
“401 or authentication errors”
Echo the variable (echo $GRAVITASK_API_KEY) in the same shell to confirm it is set, and regenerate the key from Settings > API & MCP if it was revoked.
Something else?
The full MCP setup guide covers the complete tool list, permission levels, and general troubleshooting. Using Claude or ChatGPT on the web instead? Those connect with one-click OAuth.
Next step
Ready to try it in Gravitask?
Create a workspace, then come back to this guide when you are ready to configure the workflow.
Keep reading
Related support guides
Helpful next steps from the Gravitask help centre.
AI integration
MCP Setup Guide
Connect Gravitask to AI tools through the Model Context Protocol.
Read guideAI integration
Connect Claude Code to Gravitask
Register the Gravitask MCP server with Claude Code, from the CLI or the GUI (desktop app and IDE extensions).
Read guideAI integration
Connect Cursor to Gravitask
Add the Gravitask MCP server to Cursor so the agent can read, plan and update your work.
Read guide