Connect

Connect Claude, Claude Code, and other MCP clients to your Solk installation step by step, and see how OAuth discovery works.

Claude

  1. 1

    Add the connector

    In Claude (web, desktop, or mobile), open Customize → Connectors → Browse connectors and choose Solk. Or add it yourself: + Add → Add custom connector, name Solk, URL https://mcp.solk.app/mcp (your workspace's own address https://<company>.solk.app/mcp works too). Leave the client ID fields under the advanced settings empty — Claude identifies itself automatically.

  2. 2

    Connect

    Click Connect next to the connector. Solk asks for your workspace — type yourcompany (or the full address you use to sign in) and click Continue; Solk remembers it for next time. Don't know your address? Choose I don't know my address, and Solk emails you a link to every workspace your email belongs to. Your workspace's sign-in page opens next — your password is entered only there; after you sign in, the consent screen shows the permissions Claude is requesting:

    • Read records — companies, people, opportunities, actions, email threads, calendar, and dashboards
    • Create and update records — companies, people, opportunities, tasks, notes, and activity logs; completing tasks; changing stages

    Click Allow (İzin ver) to return to Claude.

  3. 3

    Use it

    Keep Solk enabled in the chat and type your question. Claude asks for permission the first time it uses a tool; for read tools, you can choose "always allow".

Team / Enterprise: The organization owner adds the connector under Organization settings → Connectors → Add → Custom → Web. Members see the connector in their own list and click Connect to connect with their own Solk accounts — each member's permissions are limited to their own Solk role.

Claude Code

claude mcp add --transport http solk https://mcp.solk.app/mcp

Then, in Claude Code, run /mcp → solk → Authenticate and enter your workspace in the browser. To skip the workspace step, use your workspace's own address instead (https://<company>.solk.app/mcp). Claude Code uses a local redirect URI (http://localhost:<port>/callback); for loopback addresses, Solk ignores the port number during matching.

To make the server available to everyone on the project, you can set the scope to project (--scope project, written to .mcp.json); each developer still grants access with their own account.

Claude API (MCP connector)

To have Claude talk to Solk from your own application, use the Messages API's MCP connector: the request carries the anthropic-beta: mcp-client-2025-11-20 header, the Solk URL in mcp_servers, and an mcp_toolset with the same name in tools.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What do I need to do today in Solk?"}],
    "mcp_servers": [{
      "type": "url",
      "url": "https://ornek.solk.app/mcp",
      "name": "solk",
      "authorization_token": "sk_…"
    }],
    "tools": [{"type": "mcp_toolset", "mcp_server_name": "solk"}]
  }'
  • authorization_token: an API key (sk_…) an admin creates under Settings → Developers — tools run with the permissions of the person who created the key, with both scopes. To act on behalf of a user, pass an access token from your own OAuth flow instead (mcp_…, valid for 1 hour; refresh).
  • The key travels to Anthropic with the request; keep it server-side, never in a browser.
  • To turn off specific tools, add default_config / configs to the tools entry (for example read tools only).

ChatGPT, Cursor, VS Code, and others

In clients that support remote MCP servers (Streamable HTTP), enter https://mcp.solk.app/mcp or your workspace's own address. Clients that support OAuth handle discovery themselves (client ID metadata documents and dynamic client registration both work). For clients that don't, an admin can create an API key and provide it in an Authorization: Bearer sk_… header — in that case, tools run with the permissions of the admin who created the key and with both scopes.

Single address and your workspace's address

https://mcp.solk.app/mcp https://<company>.solk.app/mcp
Who uses it Claude's connector directory; anyone who doesn't want to look up an address Admins and developers who connect to one workspace
Workspace Asked once when you connect (remembered) Fixed by the address
Sign-in and consent On your workspace (<company>.solk.app) On your workspace
Tokens Prefixed with your workspace (<company>.solk.app~mcp_…) mcp_…
Permissions, limits, IP allowlist Same — the request is handled by your workspace Same

mcp.solk.app only routes the request: it stores no passwords, codes, tokens or record data; PKCE and token checks happen in your workspace. Your workspace sees the client's real IP address, so an IP allowlist works the same way.

How OAuth discovery works

Clients need no extra configuration; the flow follows the standards (MCP Authorization, OAuth 2.1). With the single address, the authorization server is https://mcp.solk.app; the steps are the same:

  1. The client sends POST /mcp without a token → 401 and WWW-Authenticate: Bearer … resource_metadata="https://ornek.solk.app/.well-known/oauth-protected-resource/mcp".
  2. The client reads the protected resource metadata (RFC 9728) → authorization server https://ornek.solk.app.
  3. It reads the authorization server metadata (RFC 8414).
  4. It registers itself (RFC 7591) or uses the URL of its client metadata document (CIMD) as the client_id.
  5. It redirects the user to the consent screen with PKCE (S256) and exchanges the code for a token.
  6. It sends MCP requests with Authorization: Bearer mcp_… and refreshes the token when it expires.

Protocol details

Transport Streamable HTTP, JSON responses (no SSE streaming)
Protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
Methods initialize, tools/list, tools/call, ping, and notifications
GET /mcp 405 (no server-to-client streaming)
Session Stateless; Mcp-Session-Id is not required
Insufficient scope If a write tool is called without crm.write: 403 + WWW-Authenticate: … error="insufficient_scope"; a delete tool called without crm.delete returns isError: true and explains how to reconnect with the Permanent delete box ticked
curl https://ornek.solk.app/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'