SectionConnect your AI: server address and sign-in

Connect your AI: server address and sign-in

How to connect Claude, ChatGPT, Cursor or your own agent to Syncra: the server address, how a person grants access, and the OAuth sign-in for a client you write yourself.

You can connect an AI app to Syncra: Claude, ChatGPT, Cursor or an agent you wrote yourself. The connection uses MCP (Model Context Protocol), an open standard that lets an AI app call actions in an outside service. Once connected, the app reads and writes in Syncra as the person who connected it, with that person’s rights. Any member of a workspace can connect an app. No admin role is needed and there is no key to create in settings: the person signs in to Syncra in a browser and presses Allow.

Server address

https://ai-syncra.ru/api/mcp

You can also copy the address inside Syncra. Open the Preferences window: it opens from the account menu in the sidebar, or with Cmd+, on macOS and Ctrl+, on Windows and Linux. Go to the Connected apps section. In the Connect an app group there is a Copy button next to the address.

Property Value
Transport MCP Streamable HTTP. There are no sessions. The server answers with plain JSON
Sign-in OAuth 2.1: authorization code with PKCE (S256 only) and a refresh token
Scope One: mcp
Access token Starts with syncat_, valid for 3600 seconds
Refresh token Starts with syncrt_, valid for 90 days, replaced on every use

What the app gets

  • The app acts as the person. It sees the channels, direct messages, tasks and knowledge base pages that person sees, and it can send messages and create and change tasks and pages.
  • Access covers every workspace of that person. There is no read-only mode and no access limited to one workspace.
  • The access token opens /api/mcp only. No other Syncra address accepts it.
  • The app cannot grant access to another app. Only a person can press Allow.
  • A message sent by the app does not mark the person’s chats as read.

The actions, group by group, are on the page Tools for your AI.

How connecting works

  1. In Syncra, the person opens Preferences, goes to the Connected apps section and presses Copy next to the address.
  2. In the AI app they add a new remote MCP connection and paste the address. If the app asks for a connection type, they choose Streamable HTTP.
  3. The app opens a browser on a Syncra page. If the person is not signed in, Syncra asks them to sign in.
  4. The consent page opens. Its title is the app’s name followed by wants to use Syncra as you. Below it says Signed in as with the email address, and there is a link Use another account. A line that starts with “After you answer, you go back to …” says where the browser goes next: the app’s website, a local address, or, for a desktop app, its own link scheme such as cursor.
  5. The person presses Allow. The browser returns to the app, and the Syncra tools appear in it. If the person presses Deny, the app gets no access.

The page carries a warning: “Allow only if you started connecting Syncra in this app yourself just now.” If you did not start a connection yourself, press Deny.

The link to the consent page is valid for 15 minutes and works once. After that the page shows This request has expired, and you start the connection again in the app.

Steps for Claude, ChatGPT and Cursor

The makers of these apps name their menus themselves and rename them from time to time. The steps below give the order of actions. If an item is named differently, look for the words “connectors” or “MCP”.

Claude

  1. Open Claude’s settings and the connectors section.
  2. Add a custom connector: enter a name, for example Syncra, and paste the address https://ai-syncra.ru/api/mcp.
  3. Start the connection. Claude opens a Syncra page in the browser. Press Allow there.

In Claude Code you add the server with a terminal command:

claude mcp add --transport http syncra https://ai-syncra.ru/api/mcp

Then run the /mcp command in Claude Code, pick syncra and finish the sign-in in the browser.

ChatGPT

  1. Open ChatGPT’s settings and the connectors section.
  2. Create a new connector, paste https://ai-syncra.ru/api/mcp as the MCP server address and choose OAuth as the sign-in.
  3. ChatGPT opens a Syncra page in the browser. Press Allow there.

If ChatGPT’s settings have no item for a custom connector, check ChatGPT’s own help. Whether you can add custom connectors depends on your ChatGPT plan and settings.

Cursor

  1. Open the file .cursor/mcp.json in the project folder. To make the server available in every project, use ~/.cursor/mcp.json.
  2. Add the server:
{
  "mcpServers": {
    "syncra": {
      "url": "https://ai-syncra.ru/api/mcp"
    }
  }
}
  1. In Cursor’s settings, in the list of MCP servers, start the sign-in for syncra. A Syncra page opens in the browser. Press Allow there.

How to disconnect an app

Open Preferences, section Connected apps. Under the heading AI apps that act as you you see the connected apps. Each row says when the app was connected and when it was last used, or not used yet. Press Disconnect. The app loses access at once. To bring it back, connect it again.

The app itself can give up its access with POST /api/oauth/revoke, described below.

Your own agent: OAuth sign-in

Ready-made MCP clients run the sign-in on their own and need only the server address. This section is for you if you write the client yourself. The order is: discover the addresses, register a client, send the person to the consent page, exchange the code for tokens, refresh the access token.

Client registration is open: nobody at Syncra approves it. The person grants access on the consent page.

GET /.well-known/oauth-protected-resource/api/mcp

Returns the authorization server that protects /api/mcp. The same answer comes from /.well-known/oauth-protected-resource.

curl "https://ai-syncra.ru/.well-known/oauth-protected-resource/api/mcp"

Response 200:

{
  "resource": "https://ai-syncra.ru/api/mcp",
  "authorization_servers": ["https://ai-syncra.ru"],
  "scopes_supported": ["mcp"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Syncra"
}

GET /.well-known/oauth-authorization-server

Returns the addresses and capabilities of the authorization server.

curl "https://ai-syncra.ru/.well-known/oauth-authorization-server"

Response 200:

{
  "issuer": "https://ai-syncra.ru",
  "authorization_endpoint": "https://ai-syncra.ru/api/oauth/authorize",
  "token_endpoint": "https://ai-syncra.ru/api/oauth/token",
  "registration_endpoint": "https://ai-syncra.ru/api/oauth/register",
  "revocation_endpoint": "https://ai-syncra.ru/api/oauth/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post", "client_secret_basic"],
  "revocation_endpoint_auth_methods_supported": ["none", "client_secret_post", "client_secret_basic"],
  "scopes_supported": ["mcp"],
  "authorization_response_iss_parameter_supported": true
}

POST /api/oauth/register

Registers a client and returns its client_id.

Parameter Type Required Description
redirect_uris array of strings yes 1 to 10 redirect addresses, each up to 2000 characters. Rules below
client_name string no The app’s name, shown to the person on the consent page. Up to 200 characters. If you leave it out, Syncra uses the host of the first redirect address
client_uri string no The address of the app’s site
token_endpoint_auth_method string no How the client proves itself at the token step: none, client_secret_post or client_secret_basic. Default: client_secret_basic
grant_types array of strings no Only authorization_code and refresh_token are allowed
response_types array of strings no Only code is allowed

Rules for a redirect address:

  • https: any host;
  • http: only localhost, 127.0.0.1 and [::1]. At sign-in the port may differ from the registered one;
  • an app’s own scheme, for example myapp://callback, is allowed;
  • the schemes javascript:, data:, file:, vbscript:, blob: and about: are forbidden;
  • the address must not have a part after #.
curl -X POST "https://ai-syncra.ru/api/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My agent",
    "redirect_uris": ["https://agent.example.com/callback"],
    "token_endpoint_auth_method": "none"
  }'

Response 201:

{
  "client_id": "syncc_...",
  "client_id_issued_at": 1762732800,
  "client_name": "My agent",
  "redirect_uris": ["https://agent.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp"
}

A client with the method none gets no secret. It proves itself with PKCE instead: the code_challenge and code_verifier pair described below. For client_secret_post and client_secret_basic the response has two more fields: "client_secret": "syncs_..." and "client_secret_expires_at": 0. The secret is shown in this response only.

An error comes with status 400, for example:

{
  "error": "invalid_redirect_uri",
  "error_description": "redirect_uris must list 1 to 10 URLs."
}

GET /api/oauth/authorize

Starts the sign-in: your app sends the person’s browser to this address.

Parameter Type Required Description
response_type string yes Always code
client_id string yes The id from the registration response
redirect_uri string yes, if the client has more than one redirect address Must match a registered one. For http on a local address the port may differ
code_challenge string yes SHA-256 of code_verifier in base64url, 43 to 128 characters from A-Z, a-z, 0-9, -, _
code_challenge_method string yes Always S256
state string no Comes back unchanged in the redirect address
scope string no Only mcp is allowed
resource string no If sent, it must point at /api/mcp of this server

One way to make code_verifier and code_challenge:

VERIFIER=$(openssl rand -base64 60 | tr -d '=+/\n' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')

The address to open in the browser:

https://ai-syncra.ru/api/oauth/authorize?response_type=code&client_id=syncc_...&redirect_uri=https%3A%2F%2Fagent.example.com%2Fcallback&code_challenge=<CHALLENGE>&code_challenge_method=S256&state=<STATE>&scope=mcp&resource=https%3A%2F%2Fai-syncra.ru%2Fapi%2Fmcp

Syncra answers with status 302, or 429 above the rate limit. Where the browser goes depends on the request.

If the request is valid, the browser lands on the consent page https://ai-syncra.ru/oauth/consent?request=<id>. When the person presses Allow, the browser goes to the redirect address with a code:

https://agent.example.com/callback?code=syncode_...&state=<STATE>&iss=https%3A%2F%2Fai-syncra.ru

If the person presses Deny, the browser goes to the redirect address with an error:

https://agent.example.com/callback?error=access_denied&error_description=The+person+declined.&state=<STATE>&iss=https%3A%2F%2Fai-syncra.ru

If Syncra knows the client but another parameter is wrong, for example code_challenge or scope, the browser goes straight to the redirect address with the same error and error_description parameters, and the person never sees the consent page.

If Syncra does not know the client_id, or the redirect address is not registered, the browser does not return to the app. The person sees the page This connection link does not work.

The code in the redirect address is valid for 10 minutes and works once.

POST /api/oauth/token

Exchanges the code for tokens and refreshes the access token. The request body is a form (application/x-www-form-urlencoded); JSON is accepted too.

Parameter Type Required Description
grant_type string yes authorization_code or refresh_token
code string for authorization_code The code from the redirect address
code_verifier string for authorization_code The string code_challenge was made from: 43 to 128 characters from A-Z, a-z, 0-9, -, ., _, ~
redirect_uri string no If sent, it must equal the address used in the authorize request
refresh_token string for refresh_token A valid refresh token
client_id string yes The client id. A client with the method client_secret_basic sends it in the header
client_secret string for client_secret_post The client secret

A client proves itself the way it chose at registration. Method none: only client_id in the body. Method client_secret_post: client_id and client_secret in the body. Method client_secret_basic: the header Authorization: Basic with client_id:client_secret in base64. Any other way returns 401 with the error invalid_client.

Exchanging the code:

curl -X POST "https://ai-syncra.ru/api/oauth/token" \
  -d "grant_type=authorization_code" \
  -d "code=syncode_..." \
  -d "code_verifier=$VERIFIER" \
  --data-urlencode "redirect_uri=https://agent.example.com/callback" \
  -d "client_id=syncc_..."

Response 200:

{
  "access_token": "syncat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "syncrt_...",
  "scope": "mcp"
}

Refreshing the access token:

curl -X POST "https://ai-syncra.ru/api/oauth/token" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=syncrt_..." \
  -d "client_id=syncc_..."

Response 200 of the same shape: a new access token and a new refresh token. The old refresh token stops working, so store the new one.

If a code or an already used refresh token is presented a second time, Syncra revokes the app’s whole access, and the person has to connect it again. This rule limits the damage if someone steals a token.

An error comes with status 400, for example:

{
  "error": "invalid_grant",
  "error_description": "The code is invalid or was already used."
}

POST /api/oauth/revoke

Revokes the app’s access. Either token of the pair is enough, and Syncra revokes the whole connection.

Parameter Type Required Description
token string yes The access token or the refresh token
client_id string yes The client id. The client proves itself the same way as at the token step
curl -X POST "https://ai-syncra.ru/api/oauth/revoke" \
  -d "token=syncrt_..." \
  -d "client_id=syncc_..."

Response 200 with an empty body. An unknown token is not an error.

First call

POST /api/mcp

Takes one MCP request in JSON-RPC 2.0 and returns the answer as JSON.

Header Required Value
Authorization yes Bearer syncat_...
Content-Type yes application/json
Accept yes application/json, text/event-stream. The MCP transport asks for both types, although the server always answers with JSON
curl -X POST "https://ai-syncra.ru/api/mcp" \
  -H "Authorization: Bearer syncat_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_workspaces","arguments":{}}}'

Response 200:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "..." }
    ]
  }
}

The text field holds Syncra’s answer as a JSON string: parse it once more. The method tools/list returns the list of tools with a description of their parameters. How tool calls and tool errors work is described on the page Tools for your AI.

Status Response body What happened
401 {"error":"invalid_token"} The Authorization header is missing, or the token is wrong, expired or revoked. The response header WWW-Authenticate carries resource_metadata with the address of the server description
405 {"error":"method_not_allowed"} A GET or DELETE request. The server takes POST only
406 a JSON-RPC error with code -32000 The Accept header lacks application/json or text/event-stream

On a 401, refresh the access token. If the refresh token does not work either, the person has disconnected the app or its access was revoked. Start the sign-in again.

OAuth errors

Errors of registration, token exchange and revocation share one shape: {"error":"<code>","error_description":"<text>"}. The status is 400, and 401 for invalid_client.

Error Where it appears What it means
invalid_redirect_uri registration A redirect address breaks the rules
invalid_client_metadata registration The body is not a JSON object, or it names a method, grant type or response type that is not allowed
invalid_client token, revoke Unknown client_id, or the client proved itself in a way other than the registered one
invalid_request authorize, token A required parameter is missing, or PKCE is set up wrong
invalid_grant token The code or refresh token is wrong, expired, already used or issued to another client
unsupported_grant_type token grant_type is neither authorization_code nor refresh_token
unsupported_response_type authorize response_type is not code
invalid_scope authorize A scope other than mcp was requested
invalid_target authorize resource does not point at /api/mcp
access_denied authorize The person pressed Deny

Errors of the authorize step do not come as a response body. They come as the error and error_description parameters in the redirect address.

Limits

Address Limit
POST /api/oauth/register 20 requests per hour from one IP address
GET /api/oauth/authorize 60 requests per minute from one IP address
POST /api/oauth/token 120 requests per minute from one IP address
POST /api/oauth/revoke 60 requests per minute from one IP address

Above the limit the server answers 429 with the body {"error":"Too many requests"}. The response has no Retry-After header.

What does not exist:

  • scopes other than mcp: read-only access or access to one workspace;
  • sign-in without a person: the client credentials, implicit and device flows;
  • a developer console for registering apps. A client registers with POST /api/oauth/register;
  • sessions, streamed responses and notifications from the server to the client;
  • MCP resources and prompts. The server offers tools only.

The address /api/mcp, the discovery addresses and the register, token and revoke requests can be called from a browser on any site: the server answers with the header Access-Control-Allow-Origin: *.