Connect ChatGPT, Claude, MCP and the CLI

The customer dashboard is separate from the API origin. Follow dashboard links returned by Artie, especially setup and conversation links. Do not prepend the API origin to a dashboard-relative route.

1. In your host's MCP or custom-connector settings, add the appropriate MCP server URL above. The exact host labels and availability depend on its version and account; custom setup is separate from an app directory listing.
2. Complete the server's normal OAuth sign-in. The protected resource advertises its authorization server through /.well-known/oauth-protected-resource/api/mcp. A 401 challenge points to that metadata.
3. If Artie returns status: "setup_required", open the returned setupUrl. Sign in as yourself, select an eligible workspace, review the client binding and connect it using the normal account flow. The URL contains an expiring binding; do not construct, copy to another person, or replace its nonce.
4. Call connection_status and doctor. Confirm the environment and workspace are the ones you intend to use before starting work.
5. Call list_artisans to choose an eligible hired Artisan. Use its returned UUID when a name is ambiguous.

OAuth sign-in and the workspace connection are different steps. An authenticated but unenrolled client does not have permission to run business commands. A disconnected or revoked grant can return setup instructions; an expired token needs authentication recovery. A workspace's two-step authentication requirement applies to connected MCP and REST calls.

A host's cached tool catalog can be stale after a release. Use the host's supported refresh mechanism when tools are demonstrably missing; reconnecting or creating another workspace grant is not a general solution to a tool-result problem.

Use Node.js 22 or later and a release-provided CLI tarball while public npm publication is pending:

npm install --global ./artie-cli-VERSION.tgz
artie --help
artie login --origin https://api.artie.ai --profile work
artie whoami --profile work --json
artie doctor --profile work --json

Public npm installation is not available yet. Obtain an approved CLI release tarball from Artie; replace VERSION with the version in its filename.

For development, choose a separate profile:

artie login --origin https://dev.artie.ai --profile development
artie doctor --profile development --json

The exact supported production and development origins select their registered delegated public CLI client and PKCE flow by default. Other origins require an explicitly registered client:

artie login --origin https://api.example.com --client-id REGISTERED_PUBLIC_CLIENT_ID --flow pkce --profile custom

Client IDs are public configuration; they are not access tokens. Use your registered client, not another person's copied session. A custom client defaults to device flow unless a flow is supplied. Device flow requires an advertised device endpoint and grant. PKCE and device flows do not silently fall back to each other.

The CLI stores access and rotating refresh credentials in the OS credential store. It does not accept bearer credentials through command arguments, environment variables, stdin or dotenv, and has no plaintext fallback. Profiles contain public configuration. Pending requests and reports under ~/.config/artie can contain submitted work; keep that directory private.

macOS ARM64 is the currently validated platform. Linux and other architectures are not yet validated for end-to-end use; Windows is unsupported. Keep npm optional dependencies enabled to install the native credential-store adapter.

Use OAuth access tokens from the advertised authorization server with the exact MCP resource audience for the environment, even for REST calls. Send them in the Authorization: Bearer header. An ID token, a cookie, a different environment's token, or a borrowed/impersonated identity is not interchangeable with this credential.

The server derives the workspace and actor from the verified token and enrolled grant. Delegated request examples do not need a client-supplied workspace, role or permission.

GET /api/v1/me HTTP/1.1
Host: api.artie.ai
Authorization: Bearer <OAUTH_ACCESS_TOKEN>

<OAUTH_ACCESS_TOKEN> is illustrative only. Your application should obtain and protect tokens through its OAuth client; never put real tokens into documentation, source, logs or support screenshots.

The live schema reference is GET /api/v1/openapi.json. It is generated from the same source contracts. Use the schema served by your deployed environment when checking available fields.

Resource metadata is available at /.well-known/oauth-protected-resource/api/mcp. Follow its advertised authorization server and use the exact environment’s MCP resource audience for both MCP and delegated REST. MCP uses Streamable HTTP POST at /api/mcp, one JSON-RPC request per body. GET and DELETE return 405; there is no persistent SSE GET endpoint. Tokens belong only in the Authorization header. Do not use ID tokens, browser cookies, machine credentials or another environment’s bearer.

GET /api/v1/doctor HTTP/1.1
Host: api.artie.ai
Authorization: Bearer <OAUTH_ACCESS_TOKEN>