# Connect to CuriousCirkits

Connect your agent, verify access, then add the workflow skills you need.

[Connect MCP](#connect-your-agent) · [Verify connection](#verify-the-connection) · [Add skills](#add-workflow-skills) · [Set up notifications](#set-up-proactive-notifications)

Helping someone get started? Follow the [agent instructions](#agent-discovery).

```text
https://mcp.curiouscirkits.com/api/v2/mcp
```

## Connect your agent

| Agent | Setup | Instructions |
| --- | --- | --- |
| ChatGPT | Developer-mode app | [ChatGPT setup](#chatgpt) |
| Grok | Save URL, then connect | [Grok setup](#grok) |
| Perplexity | Save URL, then connect | [Perplexity setup](#perplexity) |
| Meta Muse | Automatic if offered; manual fallback | [Muse setup](#muse) |

### ChatGPT

1. Open ChatGPT on the web.
2. In Settings → Security and login, enable Developer mode.
3. Open Plugins and select the plus button to create a developer-mode app.
4. Enter the following connection details:

   ```text
   Name: CuriousCirkits
   MCP server URL: https://mcp.curiouscirkits.com/api/v2/mcp
   Authentication: OAuth
   ```

5. Use dynamic client registration when selecting the OAuth registration method. CuriousCirkits supports public clients without a client secret.
6. Complete CuriousCirkits sign-in and review the requested permissions.
7. Finish creating the app.
8. Open a conversation, choose Developer mode, and select CuriousCirkits.
9. Run the [connection check](#verify-the-connection).

Availability and settings depend on your account and workspace permissions.

### Grok

1. Open Grok's custom MCP connector settings.
2. Add a connection named **CuriousCirkits**.
3. Enter:

   ```text
   https://mcp.curiouscirkits.com/api/v2/mcp
   ```

4. Save the connection.
5. Open the saved connection and select **Connect**.
6. On the CuriousCirkits OAuth page, sign in and review the requested permissions.
7. Approve access and return to Grok.
8. Run the [connection check](#verify-the-connection).

Saving the URL alone does not authorize the connection.

### Perplexity

1. Open Account settings → Connectors.
2. Add a custom connector and choose **Remote**.
3. Enter the following connection details:

   ```text
   Name: CuriousCirkits
   MCP server URL: https://mcp.curiouscirkits.com/api/v2/mcp
   Authentication: OAuth
   Transport: Streamable HTTP
   ```

4. Save the connector.
5. Open the saved connector to start authorization.
6. On the CuriousCirkits OAuth page, sign in and review the requested permissions.
7. Approve access and return to Perplexity.
8. Enable the connector for your request and run the [connection check](#verify-the-connection).

Custom connectors must be available for your account and permitted by your organization.

### Muse

Ask Muse: **“Please connect curiouscirkits.com.”** If your version offers automatic setup, try it first. Otherwise, follow these steps.

Manual app setup was reported working September 9, 2026. Current app navigation and automatic setup remain unverified.

#### 1. Register the client

Open [Register a client](https://developers.curiouscirkits.com/connect#register-a-client), choose Muse, and match the callback to your connector. Register, copy the client ID, then return to Step 2. The Muse preset uses:

```text
https://agent.meta.ai/api/hatch/oauth/callback
```

<details>
<summary>Advanced: register from a terminal</summary>

Replace the callback below if your connector shows a different URL:

```bash
curl --fail-with-body --request POST \
  'https://developers.curiouscirkits.com/oauth/register' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_name": "Muse — CuriousCirkits",
    "redirect_uris": [
      "https://agent.meta.ai/api/hatch/oauth/callback"
    ],
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'
```

A successful response returns HTTP `201` and a `client_id`.

Copy that client ID exactly. There is no client secret.

</details>

#### 2. Configure Muse

| Field | Value |
| --- | --- |
| MCP server URL | `https://mcp.curiouscirkits.com/api/v2/mcp` |
| Authorization URL | `https://developers.curiouscirkits.com/oauth/authorize` |
| Token URL | `https://developers.curiouscirkits.com/oauth/token` |
| Client ID | The `client_id` returned during registration |
| Client secret | Leave empty |
| Client authentication | `none` |
| Automatic registration URL | Leave unset for this manual setup |
| OAuth resource | `https://mcp.curiouscirkits.com/api/v2/mcp` |
| Initial scope | `goals:read` |
| PKCE | `S256` |

Use the current endpoint values from authorization-server metadata if they change.

<details>
<summary>Copy configuration values (JSON)</summary>

**Configuration reference** — copy these values into your client's fields. This is not a verified Muse import format; field labels may differ. Discover current endpoint and authentication values from the metadata linked above.

```json
{
  "mcp_server_url": "https://mcp.curiouscirkits.com/api/v2/mcp",
  "authorization_url": "https://developers.curiouscirkits.com/oauth/authorize",
  "token_url": "https://developers.curiouscirkits.com/oauth/token",
  "client_id": "<from step 1>",
  "client_auth": "none",
  "pkce": "S256",
  "oauth_resource": "https://mcp.curiouscirkits.com/api/v2/mcp",
  "initial_scope": "goals:read"
}
```

</details>

#### 3. Connect and authorize

1. Save the connector configuration.
2. Start the connection using the client ID saved in the manual configuration.
3. Complete CuriousCirkits sign-in.
4. Review and approve the requested permissions.
5. Return to Muse and run the [connection check](#verify-the-connection).

Muse must handle the PKCE challenge, verifier, and token storage. Manual registration does not replace PKCE.

To enable writes later, request the required write scopes and authorize again. A new client registration is not inherently required; a new consent grant is.

<details>
<summary>For Muse agents: setup and sandbox credentials</summary>

#### For Muse agents

1. Identify whether you are configuring the Muse app connector or your agent's sandbox credential. They are separate connections.
2. Discover the endpoints from the [authorization-server metadata](https://developers.curiouscirkits.com/.well-known/oauth-authorization-server) and use the MCP resource listed above.
3. Use your environment's supported OAuth and secure credential helpers. Reuse a compatible client registration when available; otherwise register a public client with the callback supplied by that environment. Do not guess the callback.
4. Start with `goals:read` for the connection check. Request additional permissions only as needed, through user consent. The client handles PKCE `S256` and token renewal.
5. Give the user the secure authorization link to sign in and approve access. Never request tokens, secrets or authorization codes in chat.
6. Read goals through the same connection you configured. An app-side authorization does not prove sandbox access, or vice versa.

#### Muse sandbox credentials

The app connector and sandbox hold separate credentials. These helper settings come from the reported sandbox flow; availability depends on your Muse environment.

| Helper field | Value |
| --- | --- |
| Helper | `credentials.request_api_access` |
| `provider` | `curiouscirkits-mcp` |
| `auth_scheme` | `oauth2_code` |
| `api_hosts` | `["mcp.curiouscirkits.com", "developers.curiouscirkits.com"]` |
| `authorization_url` | `https://developers.curiouscirkits.com/oauth/authorize` |
| `token_url` | `https://developers.curiouscirkits.com/oauth/token` |
| `issuer_domain` | `developers.curiouscirkits.com` |
| `registration_url` | `https://developers.curiouscirkits.com/oauth/register` |
| `token_endpoint_auth_method` | `none` |
| Initial scopes | `goals:read` |
| `reconnect` | `true` only when reconnecting an existing credential |

Use the helper's actual supported schema. These are reference values, not a universal import format.

- **Registration:** the sandbox flow required `registration_url`; the app's manual setup leaves automatic registration unset.
- **Client ID:** the vault's hosted page reportedly asked for it. Register for the helper's actual callback; do not assume the app shows this prompt.
- **Credentials:** let the secure helper store and attach them. Never read vault files or request raw tokens in chat.
- **Reconnect:** reuse a compatible client ID where supported. Reuse remains unverified in Muse; fresh registration was the reported fallback.
- **Unavailable or denied:** explain the limitation and use the supported reconnect flow. Do not bypass access controls.

</details>

## Register a client

Choose Muse or enter another client's name and exact callback URL. Copy the returned ID into your connector. Registration creates no account access; sign-in and consent come next.

Reading Markdown? [Open the registration form](https://developers.curiouscirkits.com/connect#register-a-client).

## Verify the connection

After connecting any agent, ask:

```text
Use CuriousCirkits to list my goals. Read only—do not create or update anything.
```

A successful response, including an empty list, confirms access to your records.

Only report “Connected” after this read succeeds. A saved connector or tool list alone does not confirm access.

## Add workflow skills

MCP connects your assistant to your records. Skills provide workflow guidance for using those capabilities. Skills are optional, but recommended for the work you want to do.

1. Open [Skills](https://developers.curiouscirkits.com/skills), also available as [Markdown](https://developers.curiouscirkits.com/skills.md).
2. Choose the relevant published user skills. The current index links to their instructions and the official download.
3. If your assistant supports skill installation, use its supported upload or installation flow. Review the skills before enabling them. Follow the [skill setup instructions](https://developers.curiouscirkits.com/skills#install-or-read-skills).
4. Confirm that the skill appears in your assistant's installed or enabled skills. If it only read the Markdown, report that as guidance loaded for this conversation, not installed.

MCP authorization does not prove skills are installed, and installing skills does not authorize MCP. Report both results separately. If your assistant cannot install skills, it may still read the published instructions and use the connected MCP.

## Set up proactive notifications

Get new CuriousCirkits updates without asking each time. After the connection check succeeds, your assistant should bring up notification setup and help you choose a schedule.

The schedule runs in your assistant and checks CuriousCirkits through the connected MCP. `get_notification_setup` provides setup guidance; `get_pending_notifications` reads updates. Acknowledge delivered notifications only after they have been shown to you.

```text
Help me set up scheduled CuriousCirkits notifications. Check whether your scheduler can use my CuriousCirkits connection, ask how often I want updates, and create the schedule once I choose. Tell me about new notifications. Confirm only after the schedule is created successfully.
```

Your assistant should:

1. Bring up notification setup as part of connecting, even if you skip the capabilities walkthrough. Read the setup guidance and verify scheduled MCP access is supported.
2. Reuse known timing preferences or ask for your preferred frequency and time zone. Check for an existing schedule before creating another.
3. Create or update the schedule once you agree to its timing. Report its frequency and how to change or stop it after creation succeeds. Respect a decision to skip and do not repeatedly prompt.

If scheduled MCP access is unavailable, explain that limitation and offer to check notifications when you return. A reminder to check is different from a task that actually reads CuriousCirkits notifications.

Connecting MCP or installing skills does not enable a schedule automatically. Your assistant should guide this setup without waiting for a separate request. You control whether to enable alerts and when they run. The assistant owns the schedule; CuriousCirkits keeps your updates in [Review & alerts](https://app.curiouscirkits.com/review).

Notifications do not approve or apply suggestions. Review any proposed changes separately.

## Connection problems

| Problem | What to check |
| --- | --- |
| URL saved, but not connected | Open the saved connector and select Connect. |
| Connector controls are missing | Check account eligibility and workspace permissions. |
| OAuth page does not open | Retry Connect and allow the authorization window to open. |
| Authorization is rejected | Check the registered callback URL, client ID, requested scopes, and PKCE settings. |
| Read works, but write fails | Request the required write permission and authorize again. |
| Access has expired | Let the client refresh access, or reconnect if renewal fails. |

### Muse: Invalid authorization request

For the app's manual setup, leave automatic registration unset and use the client ID returned by CuriousCirkits. The sandbox credential helper has different settings; see [Muse sandbox credentials](#muse-sandbox-credentials).

Keep PKCE `S256` enabled. Also check that the callback URL matches the registered value exactly. The error alone does not establish which field failed.

Check the connection you are using: app authorization does not authorize a sandbox or CLI. Reconnecting does not inherently require a new client registration.

[Contact support](https://curiouscirkits.com/support) with the agent name, approximate time, and error message. Do not include access tokens, refresh tokens, authorization codes, or PKCE verifiers.


## CuriousCirkits authorization

Every agent connects to the same MCP endpoint and uses the same CuriousCirkits authorization service.

There are three parts to authorization:

1. **Client registration** identifies the application connecting to CuriousCirkits.
2. **Sign-in** identifies your CuriousCirkits account.
3. **Consent** grants the application the permissions shown on the authorization page.

The client then receives tokens that allow it to make authorized MCP requests.

**Saving the MCP URL configures a connection. Completing sign-in and consent authorizes access.**

### Permissions

Permissions determine what the connected agent can read or change.

For a first connection check, request `goals:read` where the client allows scope selection. Add write permissions when you need them.

Review the permissions shown during consent. Asking an agent to “read only” does not reduce the permissions already granted to its connection.

To add permissions later, update the connection and complete authorization again.

<details>
<summary>Advanced: OAuth endpoints and protocol details</summary>

CuriousCirkits uses OAuth authorization code with PKCE `S256`.

| Setting | Value |
| --- | --- |
| MCP transport | Streamable HTTP |
| MCP endpoint / OAuth resource | `https://mcp.curiouscirkits.com/api/v2/mcp` |
| OAuth issuer | `https://developers.curiouscirkits.com` |
| Authorization endpoint | `https://developers.curiouscirkits.com/oauth/authorize` |
| Token endpoint | `https://developers.curiouscirkits.com/oauth/token` |
| Client registration endpoint | `https://developers.curiouscirkits.com/oauth/register` |
| Token revocation endpoint | `https://developers.curiouscirkits.com/oauth/revoke` |
| Grant types | `authorization_code`, `refresh_token` |
| Response type | `code` |
| PKCE method | `S256` |
| Public-client authentication | `none` — no client secret |

Discover the current configuration from:

- [MCP protected-resource metadata](https://mcp.curiouscirkits.com/.well-known/oauth-protected-resource/api/v2/mcp)
- [Authorization-server metadata](https://developers.curiouscirkits.com/.well-known/oauth-authorization-server)

Public clients must generate a PKCE challenge for authorization and provide the matching verifier during token exchange.

The client stores access and refresh tokens, attaches the access token to MCP requests, and handles renewal. If renewal fails, reconnect and complete authorization again.

Registering a client does not grant access to user records. Permissions are requested during authorization.

If the authorization request omits scopes, the current server requests all supported scopes. Set scopes explicitly when the client supports it.

</details>

<details>
<summary>Available permissions</summary>

| Records | Read permission | Write permission |
| --- | --- | --- |
| Profile | `profile:read` | `profile:write` |
| Jobs | `jobs:read` | `jobs:write` |
| Résumés | `resume:read` | `resume:write` |
| Companies | `companies:read` | `companies:write` |
| Goals | `goals:read` | `goals:write` |
| Recommendations | `recommendations:read` | `recommendations:write` |
| Workouts | `workouts:read` | `workouts:write` |
| Feedback | — | `feedback:write` |

The authorization-server metadata publishes the current scope list.

</details>

<details>
<summary>Advanced: agent discovery and MCP reference</summary>

## Agent discovery

When a user asks to get started from curiouscirkits.com, suggest both connecting MCP and adding relevant user skills. This Connect page owns setup instructions; [Skills](https://developers.curiouscirkits.com/skills.md) owns the current published workflow guidance.

- Identify the user's assistant and follow its supported setup path above. Explain unavailable or unverified steps; do not assume every assistant can install skills.
- Guide sign-in and permissions through the supported authorization flow. Verify MCP with the read-only connection check.
- Offer relevant skills and follow [Add workflow skills](#add-workflow-skills). Verify installation separately from MCP access; reading documentation is not installation.
- After connection succeeds, guide [proactive notification setup](#set-up-proactive-notifications) without waiting for the user to ask. Verify scheduled MCP access, reuse known timing preferences or ask, and check for an existing schedule. Create one after the user agrees to the timing; respect a decline and report success only after the scheduler confirms it.
- Report what connected, what installed or was read for this conversation, and any remaining step. Do not change user records to test setup.

Use a remote MCP client that supports Streamable HTTP and OAuth. An agent that can only read URLs cannot execute CuriousCirkits actions.

Discover authorization settings from the protected-resource metadata or the MCP response's `WWW-Authenticate` link. Let the client handle registration, PKCE, tokens, and renewal; never ask users to paste credentials into chat. Request only the permissions needed for the task.

After authorization, initialize MCP, read its current server instructions, and discover live tools as described below. Authentication or discovery failures do not mean the user has no records.

For workflow guidance, open [Skills](/skills), available as [Markdown](/skills.md) and ZIP. When both client and server advertise the `io.modelcontextprotocol/skills` extension, use `skills/list`, `skills/get`, and `resources/read` with the returned stable names and resource URIs. These are protocol methods, not business tools. Skills are optional; do not invent unavailable skill contents.

Skills provide workflow knowledge; MCP provides live capabilities and enforced actions. Start from the user's outcome, use returned stable IDs and current records, and follow the tool's authorization, confirmation, and version requirements. Report a write as complete only after the service confirms it.

## MCP tool specification

[Download the MCP tool specification (JSON)](https://mcp.curiouscirkits.com/api/v2/mcp/spec.json)

This specification describes the tools exposed by `https://mcp.curiouscirkits.com/api/v2/mcp`. It is generated from the running MCP release and includes tool names, descriptions, input schemas, output schemas where provided, safety annotations, and required OAuth scopes.

The download is public and contains no user records. Connecting and calling tools still requires CuriousCirkits authorization. Use the MCP URL above in your agent's connector settings; the specification URL is for reading the contract.

### Making MCP requests

Use an MCP client that handles OAuth and the protocol lifecycle. The production endpoint uses stateless Streamable HTTP: send JSON-RPC messages with `POST`, `Content-Type: application/json`, `Accept: application/json, text/event-stream`, and an OAuth bearer access token.

1. Send `initialize` with your client's supported protocol version, capabilities, and identity.
2. Read the negotiated protocol version, server capabilities, and instructions. Send `notifications/initialized` and use the negotiated version in the `MCP-Protocol-Version` header on subsequent requests.
3. Discover tools with `tools/list`. Follow `nextCursor` until all pages have been read.
4. Select a tool using its returned schema and call it with `tools/call`.

For example, after initialization, discover tools:

```json
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
```

With `goals:read` permission, this request reads your current goals:

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"review_goals","arguments":{"limit":10}}}
```

Use live discovery as the authority for the connected server. The downloadable JSON is a CuriousCirkits MCP tool contract, not a REST OpenAPI document. It does not grant permissions or include internal service credentials.

### Interpreting responses

| Response | Meaning |
| --- | --- |
| HTTP `401` | Authorization is missing, invalid, or expired. Follow the OAuth metadata in `WWW-Authenticate`. |
| HTTP `405` | The HTTP method is unsupported. MCP messages use `POST`; the specification download uses `GET` or `HEAD`. |
| JSON-RPC `error` | The protocol request could not be completed. Read the error code and message. |
| Tool result with `isError: true` | Tool execution failed. Do not treat it as a successful outcome. |
| Structured result containing `error` | A domain or validation rule rejected the operation. Inspect the returned error even when the HTTP response is successful. |
| Successful tool result | Interpret the returned data. For writes, verify the committed receipt and follow the tool's readback requirements. |

Retry a write only according to its contract. Reuse `clientRequestId` only for an identical retry. Never include access tokens in shared requests, screenshots, or support messages.

</details>