Connecting AI tools to Roleora

A connected tool can do two things. It can read your record, and it can suggest work to add to it. It cannot write to your record.

An entry written by an AI tool is a claim, not a record. It lands in your review inbox as a pending suggestion. It earns no streak credit, and it is invisible to resume and cover letter generation until you promote it yourself. Nothing you configure in a client changes that, and no client setting can turn it off.

• You finish a piece of work and ask your AI tool to log it.
• The tool calls the Roleora server with a title, a description and whatever evidence it actually has, such as a commit sha, a pull request url or a ticket key.
• The suggestion appears in your review inbox marked as agent written.
• You confirm it, edit it, or throw it away. Only a confirmed entry becomes part of your record.

So the worst case for a tool that misunderstands what it did is a suggestion you decline. It is never a wrong line on your resume.

• You need a Roleora account, and the email on it has to be the email you sign in to your AI tool with. If they differ, the server answers 403 with unknown_user and tells you to sign up with the same address first. Nothing is created for you, because signing up is where the Terms are accepted and an AI client cannot accept them on your behalf.
• Your email has to be confirmed. An unconfirmed address is a claim, not a proof, and honouring it would let anyone who can register your address elsewhere inherit your history.
• You do not need an API key, a client id, an issuer url or any other value copied by hand, unless you are using Cursor or the GitHub Copilot coding agent. Those two are covered below.

Most clients discover everything they need from the server. You give them one url, https://mcp.roleora.com/mcp, and they find the authorization server, register themselves and run the OAuth flow on their own.

claude mcp add --transport http roleora https://mcp.roleora.com/mcp

Claude Code opens your browser, runs the sign in, and stores the token itself. There is no directory approval step and nothing to paste back.

On claude.ai, open Settings, then Connectors, then Add custom connector, and paste https://mcp.roleora.com/mcp. The sign in happens in the browser tab you are already in.

Both options claude.ai offers for that connector work: Use Claude’s published identity, which is the default, and Register automatically. Either way you land on the same Roleora sign in.

On ChatGPT, turn on Developer mode, add an MCP server, and use the same url. The sign in is the same round trip.

Cursor does not run the OAuth flow, so it uses a token you create yourself on the Connections page, described under Static tokens below. Put this in .cursor/mcp.json:

{
  "mcpServers": {
    "roleora": {
      "url": "https://mcp.roleora.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ROLEORA_TOKEN}"
      }
    }
  }
}

Gemini CLI reads ~/.gemini/settings.json and takes the same shape:

{
  "mcpServers": {
    "roleora": {
      "httpUrl": "https://mcp.roleora.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ROLEORA_TOKEN}"
      }
    }
  }
}

The GitHub Copilot coding agent has no sign in path at all, so it presents a token you created on the Connections page. Configure it in the repository’s Copilot MCP settings with the secret stored as COPILOT_MCP_ROLEORA_TOKEN:

{
  "mcpServers": {
    "roleora": {
      "type": "http",
      "url": "https://mcp.roleora.com/mcp",
      "headers": {
        "Authorization": "Bearer $COPILOT_MCP_ROLEORA_TOKEN"
      },
      "tools": ["log_work_entry", "list_recent_entries", "search_entries", "get_profile_summary"]
    }
  }
}

A token like that is a credential that reaches every tool your account allows a token, so treat it the way you would treat a password. You create it, and you revoke it, on the Connections page. Nobody has to issue it for you.

Cursor and the GitHub Copilot coding agent cannot run the sign in flow, so they need a token you hand them. You create one yourself, and you can revoke it yourself.

Open Settings, then Connected apps, then the AI tools tab, and choose Create a token. Give it a name you will recognise later, like the machine or the tool it is for. The token is shown to you once, on the screen where you create it. Copy it then. It is not stored anywhere we can read, so nobody, including us, can show it to you again. If you lose it, revoke it and create another.

The token starts with rlo_. Wherever a tool asks for a header, it goes in as:

Authorization: Bearer rlo_...

A token can do exactly what you can do through a connected tool. It can read your record and suggest work for you to review, and it cannot write to your record. It counts against the same daily limit as every other tool.

You can hold five active tokens at a time. Create a sixth and we will ask you to revoke one first, which is a nudge rather than a rule about safety: tokens you have forgotten about are the ones worth removing.

A token stops working 90 days after you create it. Create a new one then, and revoke the old one.

Revoking is one click on the same page. The token stops working on the very next call the tool makes, and the row stays in your list marked revoked, so you can see what you did and when. Unlike disconnecting a tool that signed in, there is nothing left to withdraw anywhere else: the token was the whole of its access.

You sign in on roleora.com, with the login you already use. Roleora is its own sign in server for this: there is no third-party provider and no consent page hosted anywhere else. The AI tool discovers our sign in server on its own, sends your browser there, and then shows you a Roleora page listing exactly what the tool is asking for.

1. The AI tool discovers Roleora’s sign in server on its own. There is nothing for you to configure.
2. If you are not already signed in, the ordinary Roleora login appears and sends you back once you are done.
3. You sign in the normal way, with an OTP, a password or a linked account. If you already have a session, nothing is asked of you.
4. A Roleora page names the tool and lists, in plain words, what it asks for. For example: read your work entries, add draft entries for your review, read your profile summary. If it also asks to read your application profile, that is listed too, and the sensitive fields are marked.
5. Allow sends the tool its access token. Don’t allow sends it nothing, and no draft entries are created.

You will see one redirect through the ordinary Roleora login and nothing else. No third-party domain ever sees you sign in, and no separate account or credential is involved. You can disconnect any tool at any time under Settings, Connected apps, AI tools; the grant is removed right away and the tool loses access within a minute.

One account can hold several sign in identities, so a password login and a Google login both reach the same record. Changing your email address later does not break a connected tool.

The four reads declare themselves read only and the write does not, which is why a good client asks you before it runs log_work_entry and does not interrupt you for the others. Marking the write as read only would skip a confirmation you were owed, so we do not.

A tool that signs in only gets this fifth tool if it asks for it and you allow it. A token you create on the Connections page never reaches it.

One user can have at most 30 agent written entries in a day. That cap is an anti runaway rail rather than a quota to plan around, and it is returned inside the tool result, so the model reads it and stops instead of retrying what looks to it like a transport error.

• A description over 4000 characters or a title over 200 is refused, never truncated, so an agent that pasted a transcript finds out that it did.
• An unknown argument is refused. A client that put its evidence under the wrong key is told, rather than being congratulated while the evidence it sent is thrown away.
• A token minted for some other service is refused even when the same provider signed it.
• A request from a web page that is not Roleora is refused, so a page on any other site cannot reach a local MCP proxy and through it your record.

What a connected tool can see. Your confirmed entries, your unreviewed AI logged suggestions, and a summary of your profile: counts, top skills and completeness. If you allow it, also your application profile. Its sensitive fields, such as your address, date of birth and current CTC, need a second permission. Only the fields you chose to share are included.

What it cannot see. Contact details are not part of the profile summary. Nobody else’s record is reachable: the token identifies one account and every tool is scoped to that account’s own data.

What we ask tools not to send. A summary of the work, never a transcript, never a diff, and never anything read out of a .env file. The snippet we publish for repositories says exactly that, and the server strips impact claims and superlatives from what does arrive. A model can still be told to send more than it should, so treat a connected tool the way you treat any tool with access to your repository.

Disconnecting is done in the client that holds the token. Removing the server from your client stops every call it could make. Suggestions already in your review inbox stay there until you deal with them.

The discovery document is public, because a client that has never signed in has to be able to read it before it can begin. It is served at /.well-known/oauth-protected-resource and it names the resource, the authorization server and this page.

curl -s https://mcp.roleora.com/.well-known/oauth-protected-resource

An unauthenticated call to https://mcp.roleora.com/mcp answers 401 with a WWW-Authenticate header pointing at that same document, which is how a client finds its way in without being configured.

• 403, no Roleora account uses this email. The tool signed you in successfully, but that address has no Roleora account. Sign up at roleora.com with the same address, then retry. Signing in again will not help, which is why this is a 403 and not a 401.
• 401 after it worked yesterday. The token expired and the client did not renew it. Remove the server from your client and add it again.
• The tool logged something and you cannot find it in your record. That is the review gate working. Look in your review inbox, not your timeline.
• The same entry appears twice. The client sent two different dedupe keys for one piece of work. Decline the duplicate. A well behaved client uses a stable key, such as a session id or the first commit sha, so a retry after a dropped connection creates nothing.
• 404 on every call. The server is turned off for that environment. Nothing on your side will fix it, so tell us.