Zum Hauptinhalt springen

Getting Started

This guide walks you through connecting to the heycreo MCP server and making your first tool call.

heycreo runs a built-in OAuth 2.1 authorization server for its MCP endpoint. If your client supports "custom connectors" or "remote MCP servers" with OAuth (Claude, ChatGPT, and most modern MCP clients), you only need the URL: no API key, no config file.

https://app.heycreo.io/api/mcp

Add it as a custom connector and your client handles the rest: it discovers the OAuth server, opens your browser to log in to heycreo (if you aren't already), shows a consent screen where you pick which organization to grant access to, and completes the connection automatically.

See Client Examples → Claude or Client Examples → ChatGPT for step-by-step instructions.

Switching organizations later: once connected, ask the assistant to call the list-organizations or switch-organization tool, no need to reconnect or re-authenticate. See Tools Reference.

Prerequisites
  1. A heycreo account with access to at least one organization
  2. An MCP client that supports OAuth-based remote connectors (e.g. Claude, ChatGPT)

Prerequisites (API key / manual setup)​

The sections below describe the manual, API-key-based connection. It's still fully supported, and the right choice for scripts, CI, custom clients, or MCP clients without OAuth support:

  1. A heycreo organization with API access enabled
  2. An API key: create one in the heycreo app under current organization (bottom left) → API Keys
  3. An MCP-compatible client (e.g. Claude Desktop, Cursor, or a custom implementation)

Connection details​

SettingValue
SSE endpointhttps://app.heycreo.io/api/sse
HTTP endpointhttps://app.heycreo.io/api/mcp
Auth headerAuthorization: Bearer <your_api_key>
Org headerX-heycreo-Org: <your_org_slug>

The organization slug is the URL identifier of your organization (e.g. my-company from app.heycreo.io/my-company).

Authentication​

Three methods are supported, all against the same MCP endpoints above:

Enter the URL, log in through your browser, and pick an organization on the consent screen. No credentials are ever pasted into the client. See Connect with just a URL above.

Pass your API key as a Bearer token:

Authorization: Bearer heycreo_...

API keys are organization-scoped and bound to the user who created them: a key inherits that user's role and permissions in the organization it belongs to. A key can only act on its own organization; passing a different slug in X-heycreo-Org is rejected. If the creating user later leaves the organization, the key stops working and must be recreated.

JWT Token (for user-context sessions)​

If you're building a client where a user is logged in, you can use their JWT token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Organization context​

Every tool call operates within the scope of an organization.

  • OAuth connections: the organization you picked on the consent screen is used automatically. Call the switch-organization tool to change it without reconnecting.
  • API key / JWT: provide the organization slug via the X-heycreo-Org header:
X-heycreo-Org: my-company

This is required for all tool invocations that aren't using an OAuth connection.

Quick test​

Once connected, invoke the get-user-info tool (no parameters required) to verify your connection:

{
  "tool": "get-user-info",
  "arguments": {}
}

Expected response:

{
  "user": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "organization": {
    "name": "My Company"
  }
}

If you get a valid response, you're connected and authenticated.

Validate a key without an MCP client

You can also verify an API key with a plain REST call. GET /api/auth/whoami (Bearer auth, no org header needed) returns the user and the organization the key is bound to:

curl https://app.heycreo.io/api/auth/whoami \
  -H "Authorization: Bearer heycreo_your_api_key"
{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "orgId": "my-company",
  "orgName": "My Company"
}

Use the returned orgId as your X-heycreo-Org slug.

Next steps​