Connecting AI tools to Roleora

What connecting a tool actually does

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.

Before you start

• 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 verified. An unverified 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.

Connecting a client

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.

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 long lived credential that reaches every tool, 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.

Codex runs its tools inside a sandbox that blocks outbound network calls, so anything posting directly would fail inside it. Use the Roleora CLI instead: roleora log only writes to disk, and roleora sync is run outside the sandbox afterwards.

roleora log --title "Added retry to the payment webhook" \
  --description "Wrapped the Razorpay webhook handler in a bounded retry." \
  --commit "$(git rev-parse HEAD)" --skill python --skill fastapi
roleora sync

Set ROLEORA_TOKEN before syncing. A crash between the two commands loses nothing: log appends one line to a queue on disk and flushes it, and sync removes only what the server accepted, leaving the unsent tail in order.

Static tokens

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 Connections, 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.

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.

How the sign in works

You sign in on roleora.com, with the login you already use. Our authorization provider, WorkOS AuthKit, holds no password for you and does not try to sign you in itself. It hands your browser back to us, we sign you in, and then it shows you the consent screen for the tool that asked.

1. The AI client sends you to AuthKit to start the flow.
2. AuthKit redirects your browser to Roleora’s own login.
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. Roleora’s server, never your browser, tells WorkOS who you are.
5. AuthKit shows the consent screen, and the client receives its token.

You will see one redirect through a normal Roleora login. Our WorkOS credentials never reach your browser, and the only fields sent are your Roleora user id, your email and your name. No phone number, no date of birth, no settings.

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 tools

The three 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.

Limits, and what the server refuses

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.

Privacy

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.

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.

Checking the server yourself

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.

If something is not working

• 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.
• Nothing happens in Codex. Its sandbox blocks network calls. Check that the queue was written by roleora log, then run roleora sync outside the sandbox.
• 404 on every call. The server is turned off for that environment. Nothing on your side will fix it, so tell us.