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/mcponly. 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
- In Syncra, the person opens Preferences, goes to the Connected apps section and presses Copy next to the address.
- 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.
- The app opens a browser on a Syncra page. If the person is not signed in, Syncra asks them to sign in.
- 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. - 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
- Open Claude’s settings and the connectors section.
- Add a custom connector: enter a name, for example Syncra, and paste the address
https://ai-syncra.ru/api/mcp. - 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
- Open ChatGPT’s settings and the connectors section.
- Create a new connector, paste
https://ai-syncra.ru/api/mcpas the MCP server address and choose OAuth as the sign-in. - 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
- Open the file
.cursor/mcp.jsonin the project folder. To make the server available in every project, use~/.cursor/mcp.json. - Add the server:
{
"mcpServers": {
"syncra": {
"url": "https://ai-syncra.ru/api/mcp"
}
}
}
- 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: onlylocalhost,127.0.0.1and[::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:andabout: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: *.