# Connecting agents: questions and answers

Questions about connecting Claude Code, Codex, Cursor and other MCP clients
to Talewright: browser sign-in and consent, connected apps, choosing between
an API key and browser sign-in, and what an agent can and cannot do for a
member. The rules are in [Connected apps](../agents/connected-apps.md) and
[Credentials and scopes](../agents/credentials.md).

## Choosing how to connect

### How do I connect an AI agent to Talewright?

There are two ways:

- **Browser sign-in.** Claude Code and Codex send your browser to
  Talewright, where you choose workspaces and permissions and press "Allow".
- **An API key.** Any MCP client can send an API key in the `Authorization`
  header.

Both reach the MCP server at `https://app.usetalewright.com/mcp`.

More: [MCP, Client setup](../agents/mcp.md#client-setup)

### What is a connected app?

A connected app is an AI agent, such as Claude Code or Codex, that you have
allowed in the browser to work in Talewright for you. It is a credential,
like an API key: it acts for you, only in the workspaces and with the
scopes you chose.

More: [Connected apps, Summary](../agents/connected-apps.md#summary)

### What is the difference between a connected app and an API key?

A connected app is approved in the browser and holds tokens it renews by
itself; no secret is pasted anywhere. An API key is a secret you copy once.
A connected app works at MCP only. An API key works at MCP and REST.

More: [Connected apps, Where the tokens work](../agents/connected-apps.md#where-the-tokens-work)

### Should I use an API key or browser sign-in for my agent?

Use browser sign-in for Claude Code and Codex: nothing is pasted into a
file. Use an API key for any other MCP client, such as Cursor, and for
anything that calls the REST API.

More: [Connected apps, Which apps can connect](../agents/connected-apps.md#which-apps-can-connect)

### Which apps can sign in through the browser?

Claude, including Claude Code, and Codex. Talewright accepts apps whose
client ID starts with `https://claude.ai/oauth/` or
`https://chatgpt.com/oauth/codex/`.

More: [Connected apps, Which apps can connect](../agents/connected-apps.md#which-apps-can-connect)

### Can I connect an app other than Claude or Codex through the browser?

No. Any other app is refused before anyone is asked: "Talewright does not
accept this app yet." Such an app can still connect with an API key.

More: [Connected apps, Which apps can connect](../agents/connected-apps.md#which-apps-can-connect)

### Do the same rules apply to a connected app and an API key?

Yes. Both act for one member in one organization, are limited to 1 to 20
workspaces and the four scopes, expire, and never have more rights than
their member has at the moment of each request.

More: [Credentials and scopes, Summary](../agents/credentials.md#summary)

### Do I need to be an owner or admin to connect an agent?

No. Any member can connect an app for the workspaces they reach. Only
owners and admins can grant "Set file statuses".

More: [Connected apps, Who can do what](../agents/connected-apps.md#who-can-do-what)

### Do I need a Talewright account before I connect an agent?

Yes. If you are signed out when the app opens your browser, you sign in or
create an account first and come back to the same request.

More: [Connected apps, The connection, step by step](../agents/connected-apps.md#the-connection-step-by-step)

### Does the agent ever see my password?

No. You sign in to Talewright in your own browser. The app receives tokens,
never your password.

More: [Connected apps, Summary](../agents/connected-apps.md#summary)

### Does a connected app work with the REST API?

No. A connected app's access token works at `/mcp` and nowhere else. To
call the REST API, use an API key.

More: [Connected apps, Where the tokens work](../agents/connected-apps.md#where-the-tokens-work)

### Why does my connected app's token work at `/mcp` but not at `/v1`?

Access tokens of connected apps work at the MCP endpoint only. At `/v1`
they answer `401 UNAUTHENTICATED` with reason `INVALID_TOKEN`. This is
expected: connected apps work through MCP.

More: [Connected apps, Where the tokens work](../agents/connected-apps.md#where-the-tokens-work)

### Does my agent need my browser to stay open?

No. After you press "Allow", the app holds tokens of its own and talks to
the MCP server by itself. An API key works without a browser too.

More: [Connected apps, Summary](../agents/connected-apps.md#summary)

### Is there anything to install to use Talewright's MCP server?

No. The server is hosted at `https://app.usetalewright.com/mcp` and speaks
Streamable HTTP. You only add that address to your MCP client.

More: [MCP, Transport](../agents/mcp.md#transport)

### Where is the guide for agents that Talewright serves?

The app serves two plain-text guides: `https://app.usetalewright.com/llms.txt`
and `https://app.usetalewright.com/agent-guide.md`. The link "Agent guide
for Codex, Cursor and other apps" under **Settings > Connected apps** opens
the second.

More: [MCP, In the app](../agents/mcp.md#in-the-app)

## Connecting Claude Code

### How do I connect Claude Code to Talewright?

Run two commands in a terminal:

```sh
claude mcp add --transport http talewright https://app.usetalewright.com/mcp
claude mcp login talewright
```

Your browser opens Talewright, where you choose the workspaces and
permissions.

More: [Connected apps, Connect Claude Code](../agents/connected-apps.md#connect-claude-code)

### Where does the app show the command for Claude Code?

Under **Settings > Connected apps**, in the section "Connect Claude Code".
"Copy command" copies it. The command palette opens the section with
"Connect Claude Code or another agent".

More: [Connected apps, Connect Claude Code](../agents/connected-apps.md#connect-claude-code)

### How do I sign in to Talewright from inside Claude Code?

Run `/mcp` in Claude Code and choose `talewright`. From a terminal, `claude
mcp login talewright` does the same.

More: [Connected apps, Connect Claude Code](../agents/connected-apps.md#connect-claude-code)

### Why is Talewright missing when I open Claude Code in another project?

`claude mcp add` stores the server for the current project only. Add
`--scope user` to the command to have it in every project.

More: [Connected apps, Connect Claude Code](../agents/connected-apps.md#connect-claude-code)

### How do I connect Claude Code with an API key instead of browser sign-in?

Add the key as a header to the first command:

```sh
claude mcp add --transport http talewright https://app.usetalewright.com/mcp \
  --header "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

More: [MCP, Client setup](../agents/mcp.md#client-setup)

### What should I do in Claude Code after I revoke the API key it uses?

Remove the server from Claude Code's configuration. Claude Code stores the
key there, and a revoked key answers `401` on every request.

More: [MCP, Client setup](../agents/mcp.md#client-setup)

### Can I connect Claude Code on two computers to the same organization?

Yes. Each computer signs in on its own and gets a connection of its own,
with its own tokens. Both keep working, and each is listed with the time it
was connected.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### Does signing in from Claude Code on a second computer end the connection on the first?

No. Connecting the same app again for the same organization adds a second
connection. It never ends or changes an earlier one.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### Why does Claude Code say it is not authorized for Talewright?

The MCP endpoint answered `401`. Either Claude Code has not signed in yet,
or its connection ended: it was disconnected, revoked after a password
change, or its lifetime ran out. Run `claude mcp login talewright`
to sign in again.

More: [Connected apps, Disconnecting](../agents/connected-apps.md#disconnecting)

## Connecting Codex

### How do I connect Codex to Talewright?

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.talewright]
url = "https://app.usetalewright.com/mcp"
```

Then run `codex mcp login talewright` and approve the workspaces and scopes
in the browser.

More: [Connected apps, Connect Codex](../agents/connected-apps.md#connect-codex)

### How do I connect Codex with an API key?

Set `TALEWRIGHT_API_KEY` in Codex's environment and add
`bearer_token_env_var = "TALEWRIGHT_API_KEY"` to the
`[mcp_servers.talewright]` table.

More: [MCP, Client setup](../agents/mcp.md#client-setup)

### Can Codex use both browser sign-in and an API key for Talewright?

No. Use one of the two. Do not set the bearer token variable and also sign
in through the browser.

More: [MCP, Client setup](../agents/mcp.md#client-setup)

## Connecting Cursor and other MCP clients

### How do I connect Cursor to Talewright?

With an API key, in `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "talewright": {
      "url": "https://app.usetalewright.com/mcp",
      "headers": { "Authorization": "Bearer ak1_REPLACE_WITH_YOUR_KEY" }
    }
  }
}
```

Keep that file private.

More: [MCP, Client setup](../agents/mcp.md#client-setup)

### Can Cursor sign in to Talewright through the browser?

No. Browser sign-in is accepted for Claude and Codex. Other MCP clients,
such as Cursor, connect with an API key.

More: [Connected apps, Which apps can connect](../agents/connected-apps.md#which-apps-can-connect)

### How do I connect an MCP client that is not listed?

Point it at `https://app.usetalewright.com/mcp` with Streamable HTTP, and
have it send `Authorization: Bearer ak1_...` on every request. Requests are
`POST`, without a cookie.

More: [MCP, Client setup](../agents/mcp.md#client-setup)

### Which scopes should the API key of an MCP client have?

Only the ones the agent's task needs. A credential sees only the tools its
scopes allow, so fewer scopes also keep the agent's tool list short.

More: [MCP, Which tools a credential sees](../agents/mcp.md#which-tools-a-credential-sees)

### Can an agent that runs in a web page connect to Talewright?

No. A request to `/mcp` that carries an `Origin` header, as a web page
calling it from a browser would send, is refused with `403 FORBIDDEN`. MCP
is for command-line and server-side clients.

More: [MCP, Transport](../agents/mcp.md#transport)

### Can an app register itself with Talewright to connect?

No. Apps do not register with Talewright in advance, and there is no
registration endpoint. An app identifies itself by a client ID that is a
web address.

More: [Connected apps, Which apps can connect](../agents/connected-apps.md#which-apps-can-connect)

## The consent screen

### What happens in my browser when an app asks to connect?

Your browser lands on the consent screen, titled "Connect {app}". You
choose the organization, the workspaces, the permissions and the lifetime,
and press "Allow" or "Deny". Then you return to the app.

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### What does the consent screen tell me about the app?

"{app}, identified by {host}, asks to act as {your email} through
Talewright's MCP server." The host is the address that identifies the app.

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### What do I choose on the consent screen?

- "Organization": the organization the app works in.
- "Workspaces": 1 to 20 workspaces of it that you reach.
- "Permissions": the scopes the app gets.
- "Expires": 30, 90, 180 or 365 days.

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### Can I give a connecting app less than it asked for?

Yes. Untick anything it does not need. You can grant fewer scopes than the
app asked for, never more.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Can I give a connecting app a permission it did not ask for?

No. A scope the app did not ask for is not offered and cannot be granted,
whoever you are.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Why are only some permissions shown on the consent screen?

Only the scopes the app asked for are shown.

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### Which permissions does an app get when it asks for none?

It is treated as asking for `workspace:read`, `files:read` and
`files:write`. It is never treated as asking for `files:approve`.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Which permissions are ticked when the consent screen opens?

Every scope the app asked for, except `files:approve`. "Set file statuses"
is always a separate, unticked choice.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Why does "Set file statuses" start unticked although the app asked for it?

It always starts unticked. Tick it only if the app needs to set statuses.
The screen says so: "Setting file statuses requires the separate permission
you select below."

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### Why did "Set file statuses" untick itself on the consent screen?

You changed the organization or the workspaces. That unticks it again,
because it depends on your role in every chosen workspace.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Who can grant a connecting app `files:approve`?

Someone who is owner or admin in every chosen workspace. For anyone else
the choice is greyed out, and granting it answers `403 FORBIDDEN`. The
other scopes can still be allowed.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Why is a workspace already ticked on the consent screen?

You reach only one workspace of the chosen organization, so it is ticked
for you.

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### Can I connect an app to two organizations in one step?

No. One request connects one organization. Start again from the app to
connect a second organization; that makes a second connection with its own
tokens.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### What happens when I press "Allow"?

Your browser returns to the app with a one-time code. The app exchanges
the code for its tokens. At that moment the connected app is created and
appears under **Settings > Connected apps**.

More: [Connected apps, The connection, step by step](../agents/connected-apps.md#the-connection-step-by-step)

### What happens when I press "Deny"?

Your browser returns to the app with `access_denied`. Nothing is connected
and the app gets no tokens.

More: [Connected apps, The connection, step by step](../agents/connected-apps.md#the-connection-step-by-step)

### I pressed "Deny" by mistake. How do I connect the app after all?

Start again from the app. A request is answered once and cannot be opened
again.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### What happens if I press "Allow" twice or open the request in two tabs?

The first decision counts. The second finds no open request and shows
"This request has ended".

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### Can I correct my choice when "Allow" is refused?

Yes. A refused decision, for example one that names a workspace you do not
reach, leaves the request open. Correct it and decide again within the 10
minutes.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Can I allow an app with no permission ticked?

No. The screen says "Choose at least one permission." An app cannot be
connected with no scope.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### I was signed out when the app opened my browser. Is the request lost?

No. The screen "Connect an app" offers "Sign in" and "Create account". You
come back to the same request afterwards.

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### Can I connect an app when my account reaches no workspace?

No. You can only deny. Join or create an organization, then start again
from the app.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### Can someone else answer the request my app opened?

Not once you have opened it. A request belongs to the first signed-in
account that opens it. Every other account sees "This request has ended",
and through the API gets `404 NOT_FOUND` for reading and for deciding. The
app does not choose who opens it first.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### What if someone else opens my consent link before I do?

The request is theirs. You see "This request has ended". Start again from
the app, and disconnect anything that person connected if it shows up in Key
management.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### I opened the request signed in to the wrong account. Can I move it to the right one?

No. The request stays with the account that opened it first. Signing in to
the right account does not move it. Start again from the app.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### Why does a request to connect stay with the account that opened it first?

The address of the consent screen can leak, for example from a shared screen
or a pasted link. Whoever holds it must not be able to connect the app to
their own account in your place, or answer for you.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Who owns a request that is decided before anyone has read it?

The account that decides it. Deciding a request nobody has opened makes it
the decider's in the same step. A refused decision does not: the request is
left as it was.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Can an agent approve its own request to connect?

No. Answering an app's request to connect needs a person signed in with a
browser. No credential can do it.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Where do I go after I decide on the consent screen?

Back to the app. The screen says "After you decide, you return to {host}."

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### When exactly does an app become connected?

When the app exchanges its one-time code for tokens, not when you press
"Allow". If the exchange fails, nothing is connected.

More: [Connected apps, The connection, step by step](../agents/connected-apps.md#the-connection-step-by-step)

### Is my access checked again after I press "Allow"?

Yes. When the code is exchanged, Talewright checks again that you still
reach the workspaces you chose and, for `files:approve`, that you are still
owner or admin in each. If not, the exchange is refused and no app is
connected.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### Is an email sent when an app is connected?

Yes. You get a security email when the connected app is created. Owners
and admins see the app in Key management.

More: [Connected apps, The connection, step by step](../agents/connected-apps.md#the-connection-step-by-step)

## Lifetimes and tokens

### How long does a connection to an app last?

As long as you chose on the consent screen: 30, 90, 180 or 365 days. "In 90
days" is preselected. Then the app must ask you again.

More: [Connected apps, The request to connect](../agents/connected-apps.md#the-request-to-connect)

### Do I have to approve the app again every hour when its access token expires?

No. The app renews the access token by itself with its refresh token.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### Why did my agent lose access after a month without use?

A refresh token stops working after 30 days without a refresh. Sign in
again from the app.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### What happens when the lifetime of a connection ends?

Neither token outlives the connected app. When its lifetime ends, the app
must ask you again.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### Can I extend a connection without connecting again?

No. To get a later expiry, connect the app again and choose the lifetime.
That makes a new connection. The earlier one keeps working until its own
lifetime ends or you disconnect it.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### How do I change the workspaces or permissions of a connected app?

Connect it again from the app and choose differently, then disconnect the
earlier connection. A new connection does not replace an old one.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### Can a connected app give itself more permissions when it renews its token?

No. A refresh cannot change the scopes. It cannot narrow them and it cannot
add `files:approve`.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### What are the `at1_` and `rt1_` tokens?

`at1_` starts an access token, which the app sends to the MCP server.
`rt1_` starts a refresh token, which the app uses only to get new tokens.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### What happens if a one-time code or a refresh token is stolen and used again?

That connection is revoked at once. A used code or a used refresh token
that is presented again ends the connection it belongs to, which protects
you if it was intercepted. Other connections to the same app keep working.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### Can one app use another app's tokens?

No. A token works only for the app it was issued to. Another app that
presents your app's refresh token is refused, and your connection is not
affected.

More: [Connected apps, Where the tokens work](../agents/connected-apps.md#where-the-tokens-work)

### Can a refresh token be sent as a bearer token?

No. A refresh token works only at the token endpoint. Sent as a bearer
token anywhere, it answers `401`.

More: [Connected apps, Where the tokens work](../agents/connected-apps.md#where-the-tokens-work)

## Several connections per app

### Can I connect the same app twice for one organization?

Yes. Every "Allow" makes a connection of its own, with its own tokens and
its own workspaces, scopes and lifetime. Connecting again never ends or
changes an earlier connection.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### How many connections to one app can I have in one organization?

10 working ones. Revoked and expired connections do not count. Connections
to other apps and in other organizations are counted on their own.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### What happens when I allow the same app an eleventh time for one organization?

"Allow" is refused with `409 CONFLICT`, `details.reason` `CONNECTION_LIMIT`.
The consent screen says "You already have 10 connections to this app in this
organization. Disconnect one under Settings, Connected apps, then allow
again." The request stays open for its 10 minutes.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### How do I tell two connections of the same app apart?

By when each was connected, when it was last used, and the MCP client that
last used it. The app sends no name for the computer it runs on, and
Talewright does not fingerprint devices.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### Does disconnecting one connection end my other connections to the same app?

No. Each connection is refreshed, disconnected and revoked on its own.
Ending one leaves the others working.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### Can I connect the same app to two organizations?

Yes. Each organization gets its own connection, with its own tokens.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### Can I connect both Claude Code and Codex to the same organization?

Yes. Two different apps each have their own connections. The limit of 10
working connections is counted per app.

More: [Connected apps, Several connections per app](../agents/connected-apps.md#several-connections-per-app)

### What is recorded when I connect an app again?

One event: `connected_app.created` for the new connection. The earlier
connection is not touched. Each connection has its own activity.

More: [Audit trail, Edge cases](../reference/audit-trail.md#edge-cases)

## Listing and disconnecting

### Where do I see my connected apps?

Under **Settings > Connected apps**, in the table "Connected apps", newest
first. Each row is one connection, so the same app connected twice is two
rows. With none it says "No connected apps yet."

More: [Connected apps, The list of connected apps](../agents/connected-apps.md#the-list-of-connected-apps)

### What does the list show for each connected app?

The app's name, the host that identifies it, "Connected" with the date and
time, and the MCP client that last connected with it. Also its organization,
workspaces and scopes, when it expires and when it was last used.

More: [Connected apps, Listing](../agents/connected-apps.md#listing)

### How do I disconnect an app?

Press "Disconnect" on its row under **Settings > Connected apps**, then
confirm with "Disconnect". "Disconnected {name}" confirms. That ends the one
connection of that row.

More: [Connected apps, The list of connected apps](../agents/connected-apps.md#the-list-of-connected-apps)

### What happens when I disconnect an app?

Its access token and refresh token stop at once. The next MCP call answers
`401`, and the refresh token no longer exchanges.

More: [Connected apps, Disconnecting](../agents/connected-apps.md#disconnecting)

### Can I undo disconnecting an app?

No. The app must ask you again to reconnect.

More: [Connected apps, Disconnecting](../agents/connected-apps.md#disconnecting)

### What happens to the work an app did after I disconnect it?

It stays: files it uploaded, changes it made, and library proposals it
prepared, which stay for review.

More: [Connected apps, Disconnecting](../agents/connected-apps.md#disconnecting)

### What does the dialog "Disconnect {name}?" say?

"The connection made {date and time} stops working at once and must ask you
again to reconnect. Other connections to {name} keep working. Work it
prepared stays for review."

More: [Connected apps, The list of connected apps](../agents/connected-apps.md#the-list-of-connected-apps)

### In which ways can a connection to an app end?

- You press "Disconnect".
- An owner or admin revokes it in Key management.
- The app revokes its own token.
- You leave the organization or are removed from it.
- You reset or change your password, or delete your account.
- A used code or refresh token is presented again.
- The connection's lifetime ends.

More: [Connected apps, Disconnecting](../agents/connected-apps.md#disconnecting)

### Can an app disconnect itself?

Yes. An app can revoke its own token, which ends its connection.

More: [Connected apps, Revoking](../agents/connected-apps.md#revoking)

### Can an owner or admin disconnect my connected app?

Yes. Owners and admins revoke any member's connected app in Key
management. "Revoke" ends that one connection. The confirmation says
"{member}'s connected app stops working at once. They can connect it again
if they still need it."

More: [Connected apps, Key management (owners and admins)](../agents/connected-apps.md#key-management-owners-and-admins)

### What happens to a running agent when I disconnect it?

Its next tool call fails with `401`. The MCP server keeps no session, so
every request is authenticated on its own.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### How do owners and admins see the apps members connected?

In Key management, in the table "Credentials", together with API keys, one
row per connection. A connected app reads "Connected app from {host}" with
"Connected {date and time}".

More: [Connected apps, Key management (owners and admins)](../agents/connected-apps.md#key-management-owners-and-admins)

### How do I see what a connected app did?

Press "Activity" on its row under **Settings > Connected apps**. It lists
what was done with the app, newest first.

More: [Connected apps, The list of connected apps](../agents/connected-apps.md#the-list-of-connected-apps)

### What is the "last client" shown for a connected app?

The MCP client that last connected with it: its name, its version and the
MCP protocol version.

More: [Connected apps, Listing](../agents/connected-apps.md#listing)

### Which operations are behind the connected apps page?

`GET /v1/me/connected-apps` lists and
`DELETE /v1/me/connected-apps/{credentialID}` disconnects. Both are browser
only.

More: [Connected apps, Session operations behind the consent screen](../agents/connected-apps.md#session-operations-behind-the-consent-screen)

## What an agent can and cannot do for you

### What can an agent do once it is connected?

Exactly what its scopes allow, in its workspaces and in its organization
folder, as you. It reaches the organization folder (the API's library) with its
file scopes whatever workspaces you ticked. Its tool list shows only the
tools its scopes allow.

More: [Connected apps, What a connected app can do](../agents/connected-apps.md#what-a-connected-app-can-do)

### Does an agent act as me or as itself?

As you. A credential acts for exactly one member, and everything it does is
that member's action. Each change is also recorded with the credential's
ID, so it is visible as the agent's activity.

More: [Connected apps, What a connected app can do](../agents/connected-apps.md#what-a-connected-app-can-do)

### Can an agent do more than I can do myself?

No. It never has more rights than you have at that moment. A member's agent
cannot change organization folder files, because a member cannot.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Can an agent find and read my files?

Yes, with `files:read` or `files:write`: it can search files, read their
details, list folders, tags and versions, and get temporary addresses for
the bytes.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Can an agent upload files for me?

Yes, with `files:write`. In a workspace any member's agent can upload. In
the organization folder only an owner's or admin's agent can.

More: [Roles and permissions, Uploads in the organization folder](../reference/permissions.md#uploads-in-the-organization-folder)

### Can an agent rename, move, tag and describe files?

Yes, with `files:write`. It can also set field values, and create, rename,
move, trash and restore folders.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Can an agent restore something from the trash?

Yes, with `files:write`. A workspace member's agent restores workspace files
and folders. Only an owner's or admin's agent restores organization folder
ones.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Can an agent set a file's status?

Only with `files:approve`, granted explicitly by an owner or admin, and
only while that member is still an owner or admin with a verified email.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Can an agent make a file public?

Not directly. General access is set by a person in a browser. An agent
with `files:approve`, acting for an owner or admin, can set a status that
allows public use, and can confirm a move that makes files public through
a public folder.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an agent delete a file for good?

No. An agent can move files to the trash, where they stay restorable for
30 days. Deleting for good is browser only.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an agent prepare changes for me to review first?

Yes. An agent with `files:write` creates a library proposal: a batch of
suggested changes that a person reviews and applies under "Suggestions" in
the app.

More: [MCP, Library proposals](../agents/mcp.md#library-proposals)

### Can an agent apply the suggestions it made?

No. A person applies proposals in the browser. An agent can reject pending
items.

More: [MCP, Library proposals](../agents/mcp.md#library-proposals)

### Can an agent connect another agent or create an API key?

No. A credential can never create, extend or recover a credential, an
account or access.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an agent see my other connected apps and API keys?

No. Listing credentials needs a person in a browser, and MCP never shows
keys, tokens or other members' credentials.

More: [MCP, What MCP never shows](../agents/mcp.md#what-mcp-never-shows)

### Can an agent work in my other organizations?

No. A connection belongs to one organization and reaches no other, even
when you belong to several. Connect the app again for each organization.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### What happens to my agent when I am removed from one of its workspaces?

That workspace answers `NOT_FOUND` from the agent's next call. Its other
workspaces keep working.

More: [MCP, Edge cases](../agents/mcp.md#edge-cases)

### What happens when I am demoted while my app holds `files:approve`?

The app keeps the scope, but its status changes are refused with `403
FORBIDDEN`. Each use checks your role at that moment.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### How do I limit what an agent can do?

Tick only the workspaces and permissions it needs on the consent screen,
leave "Set file statuses" unticked, and choose a short lifetime. The
workspaces you tick do not limit the organization folder: every connected
app reaches its organization folder with its file scopes.

More: [Connected apps, The consent screen](../agents/connected-apps.md#the-consent-screen)

### How do I stop an agent at once?

Disconnect it under **Settings > Connected apps**, or revoke its API key
under **Settings > Credentials**. Its tokens or its key stop working
immediately.

More: [Connected apps, Disconnecting](../agents/connected-apps.md#disconnecting)

### How do I see what an agent did?

Press "Activity" on the credential's row: under **Settings > Connected
apps** for a connected app, under **Settings > Credentials** for an API
key.

More: [Audit trail, In the app](../reference/audit-trail.md#in-the-app)

### Can an agent hide what it did?

No. An event is recorded together with the change it describes, and events
are never changed and never deleted. An agent cannot read or touch the
audit trail.

More: [Audit trail, Rules](../reference/audit-trail.md#rules)

### Is an agent's proposal still there after I disconnect the agent?

Yes. Library proposals it prepared stay for review.

More: [Connected apps, Disconnecting](../agents/connected-apps.md#disconnecting)

### Who is recorded when I apply an agent's proposal?

You are. `library_proposal.created` is in the agent's activity.
`library_proposal.applied` and the resulting `file.updated` events are
yours, made in a browser session, so they are not in the agent's activity.

More: [Audit trail, Edge cases](../reference/audit-trail.md#edge-cases)

## For people who build an MCP client

### Which OAuth flow does Talewright use for connected apps?

The standard authorization code flow with PKCE. The only grant types are
`authorization_code` and `refresh_token`.

More: [Connected apps, Discovery](../agents/connected-apps.md#discovery)

### Which OAuth endpoints does Talewright have?

On `https://app.usetalewright.com`:

- `GET /.well-known/oauth-protected-resource/mcp`
- `GET /.well-known/oauth-authorization-server`
- `GET /oauth/authorize`
- `POST /oauth/token`
- `POST /oauth/revoke`

More: [Connected apps, Endpoints](../agents/connected-apps.md#endpoints)

### How does an MCP client find out how to sign in?

It calls the MCP endpoint without a token. The `401` answer carries
`WWW-Authenticate: Bearer resource_metadata="https://app.usetalewright.com/.well-known/oauth-protected-resource/mcp"`.
The client reads that document, then the authorization server document.

More: [MCP, Authentication](../agents/mcp.md#authentication)

### What does the protected resource document say?

It names the `resource` (the MCP endpoint's URL), the
`authorization_servers`, the `scopes_supported` (the four scopes) and
`bearer_methods_supported` (`header`).

More: [Connected apps, Discovery](../agents/connected-apps.md#discovery)

### What does the authorization server document say?

It gives the authorization, token and revocation endpoints, response type
`code`, response mode `query`, challenge method `S256`, token endpoint
authentication `none`, the four scopes, and that client ID metadata
documents are supported.

More: [Connected apps, Discovery](../agents/connected-apps.md#discovery)

### Does Talewright support OpenID Connect?

No. There is no OpenID Connect configuration and no registration endpoint.

More: [Connected apps, Discovery](../agents/connected-apps.md#discovery)

### Does Talewright support the client credentials or device code grant?

No. Only `authorization_code` and `refresh_token` are supported. Any other
grant type answers `unsupported_grant_type`.

More: [Connected apps, Discovery](../agents/connected-apps.md#discovery)

### How does an app identify itself to Talewright?

By a client ID that is a web address. At that address the app publishes a
small document that describes it: its name and the addresses it may return
to.

More: [Connected apps, Which apps can connect](../agents/connected-apps.md#which-apps-can-connect)

### What must an app's client metadata document look like?

It must be served over `https` with status `200` as `application/json`,
without a redirect. Its `client_id` equals its own address, it lists its
`redirect_uris`, and it has no `client_secret`. Its
`token_endpoint_auth_method` is absent or `none`.

More: [Connected apps, The client metadata document](../agents/connected-apps.md#the-client-metadata-document)

### Do connecting apps have a client secret?

No. Apps have no secret, and an app that sends one is refused with
`invalid_client`.

More: [Connected apps, Which apps can connect](../agents/connected-apps.md#which-apps-can-connect)

### Which name does the consent screen show for an app?

The `client_name` of its metadata document, cut to 100 characters. Without
one, the host of the client ID is shown.

More: [Connected apps, The client metadata document](../agents/connected-apps.md#the-client-metadata-document)

### How often does Talewright read an app's metadata document?

At every request to connect.

More: [Connected apps, The client metadata document](../agents/connected-apps.md#the-client-metadata-document)

### Which redirect addresses may an app use?

`https` addresses, or `http` on a loopback host: `127.0.0.1`, `[::1]` or
`localhost`. The address must match a listed one exactly and have no
fragment.

More: [Connected apps, The client metadata document](../agents/connected-apps.md#the-client-metadata-document)

### Can a command-line app use a different loopback port each time?

Yes. A loopback redirect address may use any port, even one that is not
listed. Command-line apps pick a free port each time.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### Which parameters does `GET /oauth/authorize` take?

`client_id`, `redirect_uri`, `response_type` (`code`), `code_challenge`,
`code_challenge_method` (`S256`) and `resource` are required. `scope` and
`state` are optional.

More: [Connected apps, The authorization request](../agents/connected-apps.md#the-authorization-request)

### Is PKCE required to connect an app?

Yes. The authorization request must carry a `code_challenge` with method
`S256`, and the code exchange must carry the matching `code_verifier`.

More: [Connected apps, The authorization request](../agents/connected-apps.md#the-authorization-request)

### What must the `resource` parameter be?

The MCP endpoint's URL, exactly as the discovery document gives it. It is
required in the authorization request and in the code exchange, and
optional in a refresh.

More: [Connected apps, The token request](../agents/connected-apps.md#the-token-request)

### What does `GET /oauth/authorize` answer?

A redirect (`302`): to the consent screen, to the app's own `redirect_uri`
with an `error`, or to the "This app cannot connect" screen. Every redirect
back to the app carries `iss` and, when given, `state`.

More: [Connected apps, The authorization request](../agents/connected-apps.md#the-authorization-request)

### What does an app send to exchange its code for tokens?

A form body to `POST /oauth/token` with `grant_type=authorization_code`,
`client_id`, `code`, `redirect_uri`, `code_verifier` and `resource`. It
sends no `Authorization` header and no `client_secret`.

More: [Connected apps, The token request](../agents/connected-apps.md#the-token-request)

### What does an app send to refresh its tokens?

`grant_type=refresh_token`, `client_id` and `refresh_token`. `resource` and
`scope` are optional; if sent, `scope` must be exactly the scopes the
connection holds.

More: [Connected apps, The token request](../agents/connected-apps.md#the-token-request)

### What does the token endpoint answer?

```json
{
  "access_token": "at1_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt1_...",
  "scope": "workspace:read files:read files:write"
}
```

The answer is never cached (`Cache-Control: no-store`).

More: [Connected apps, The token request](../agents/connected-apps.md#the-token-request)

### Does each refresh give a new refresh token?

Yes. Each refresh gives a new access token and a new refresh token. The
old refresh token is used up.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### Is the one-time code used up when the exchange fails?

Yes. The first attempt uses the code up, whether it succeeds or not. Start
again from the app.

More: [Connected apps, The code and the tokens](../agents/connected-apps.md#the-code-and-the-tokens)

### What happens when a refresh asks for fewer scopes?

It is refused with `invalid_scope`. The refresh token is not used up and
can be tried again without `scope`.

More: [Connected apps, Edge cases](../agents/connected-apps.md#edge-cases)

### How does an app revoke its own connection?

It sends `token` and `client_id` as form fields to `POST /oauth/revoke`. A
token of that app, access or refresh, revokes its connection.

More: [Connected apps, Revoking](../agents/connected-apps.md#revoking)

### Can one app revoke another app's token?

No. A token of another app changes nothing. The answer is `200` in both
cases.

More: [Connected apps, Revoking](../agents/connected-apps.md#revoking)

### Do the OAuth endpoints use my browser session?

No. These endpoints take no session, and cookies are ignored. Only the
consent screen itself needs you to be signed in.

More: [Connected apps, Endpoints](../agents/connected-apps.md#endpoints)

### Are the OAuth endpoints in the OpenAPI contract?

No. They are not part of `/v1` and not in the OpenAPI document. The two
operations behind the consent screen, under `/v1/oauth/requests/`, are.

More: [Connected apps, Endpoints](../agents/connected-apps.md#endpoints)

### What does a connected app read about itself?

The MCP tool `credential_read` returns `kind: "connected_app"`, the member
it acts for, its organization, workspaces, scopes and `expiresAt`, and
`client` with the app's `clientID` and `name`.

More: [Connected apps, Reading the connection from inside](../agents/connected-apps.md#reading-the-connection-from-inside)

### What does the decision on the consent screen send?

`POST /v1/oauth/requests/{requestID}/decision` with `allow`, and when
allowing `organizationID`, `workspaceIDs`, `scopes` and optionally
`expiresInDays`. The answer is `{ "redirectURL": "..." }`: where the
browser goes next.

More: [Connected apps, Session operations behind the consent screen](../agents/connected-apps.md#session-operations-behind-the-consent-screen)
