Skip to main content

​
Step 1: Open the Cursor interface

  1. Launch the Cursor app on your system.
  2. Log in with your account if required.

​
Step 2: Access MCP settings

  1. In the top menu, click Settings ( on the top-right) -> Cursor Settings.
  2. Navigate to the Tools & MCP section.
  3. This section allows you to add, edit, or remove MCP connections.

​
Step 3: Add Timbal as a new MCP server

  1. Click Add Custom MCP.
  2. Add the Timbal MCP URL (https://api.timbal.ai/mcp) in mcp.json. For example, you can name it "timbal-mcp":
    mcp.json
    {
    "mcpServers": {
        "timbal-mcp": {
            "url": "https://api.timbal.ai/mcp",
            // Use this to authenticate with a Timbal API Key instead of OAuth
            // "headers": {
            //     "Authorization": "Bearer <TIMBAL_API_KEY>"
            // }
        }
    }
}
  3. Save the configuration.

​
Option 1: Connect via OAuth

  1. In the Tools & MCP section, check the Installed MCP Servers list — Timbal should appear there.
  2. Click Connect.
  3. A browser window will open to complete Timbal authentication.
  4. Log in using your preferred method: GitHub, Google, Microsoft, or Timbal OAuth.
  5. Accept the OAuth permissions when prompted and continue.
  6. Return to Cursor — Timbal should now show a green indicator, and its tools will be listed.
    Make sure to log in with your active Timbal account — the account registered on the Timbal Platform. Using a different account may prevent access to Timbal tools.

​
Option 2: Connect using a Timbal Api Key

  1. If you added a "Authorization" with "TIMBAL_API_KEY" in mcp.json, Cursor will automatically use it — no browser login is needed.
  2. Check the Installed MCPs list — Timbal should appear in green, with its tools ready to use.

​
Step 4: Start using Timbal in Cursor

  1. Open the Toggle Agents Sidebar ( on top-right).
  2. Click New Agent and start a chat.
  3. You can now use Timbal tools in your conversation. Cursor will automatically leverage the MCP integration.
    The first time you try to use a Timbal tool in Cursor, you’ll need to accept the button in the chat asking if you want to run Timbal MCP.