Connect your own AI (MCP)

Connect

Your server address is shown in Account settings → Connected AI. It looks like https://your-torvany.example/api/mcp. There are two ways to connect.

1. Connect by signing in (recommended)

In an app that lets you add a connector or MCP server by its address, paste the address. The app sends you to Torvany, where you sign in, see which app is asking, pick the workspaces it may use and whether it may make changes, and approve. You go back to the app and it's connected. There's nothing to copy, and the app refreshes its own access.

2. Connect with a personal token

For apps that use a configuration file or let you set request headers. In Connected AI, choose Create token, give it a name, pick the workspaces and an expiry (up to a year, 90 days by default), and tick Allow changes only if your AI should change things. The token is shown once. Most apps accept a configuration like this:

{
  "mcpServers": {
    "torvany": {
      "type": "http",
      "url": "https://your-torvany.example/api/mcp",
      "headers": { "Authorization": "Bearer tvy_mcp_xxxxxxxx_…" }
    }
  }
}

Some apps ask for the address and the token in separate fields instead. Treat tokens like passwords and revoke the ones you no longer use.

What your AI can do

Every tool takes a workspace (its slug, from list_workspaces). Projects are named by their key, like WEB, and tasks by theirs, like WEB-12. Reading works with every connection; changes need a connection with changes allowed and are made as you.

Moving a task to the trash can be undone from the project's trash in Torvany; there's no tool that deletes anything for good.

Access & safety

• Your AI acts as you. It sees and changes only what you can, in the workspaces you picked, and every change is in the workspace's audit log.
• Connections are read-only unless you allow changes. Apps that ask for changes say so on the approval screen, and you decide.
• Workspaces must be on Pro or Business. Owners and admins can switch connecting your own AI off for their workspace in Settings → General, which stops every connection there at once.
• Owners and admins see who has connected an AI to their workspace, with what access, and can disconnect one connection from their workspace, or turn connecting off for one person there (every connection of theirs, new ones too); either keeps working in the person's other workspaces and can be undone. Admins can do this for members and viewers, owners for anyone else. Connecting, revoking and disconnecting are recorded in the audit log, and changes an AI makes are marked "via connected AI".
• Guests can't connect an AI to a workspace where they're a guest.
• If a workspace requires two-factor authentication, it only accepts connections from people who have it on, as in the app.
• If a workspace requires single sign-on, it only accepts connections made while you were signed in with single sign-on (owners excepted, as for signing in). Connections made from a password sign-in stop working there: sign in with single sign-on and connect again.
• Revoke a token or a connected app in Connected AI at any time. It stops working immediately.
• Connected AI lists what your AI changed in the last 30 days (tasks and subtasks created or edited, comments, time logged, status updates, projects, tasks moved to the trash). Undo puts each one back, done as you; an edit is only undone if nobody changed those fields since.
• Every new token or connected app sends a security email to your account's address, so you'd notice one you didn't add. Connecting an AI needs a verified email address.
• Resetting or changing your password, or signing out your other devices, also disconnects every token and connected app, in case someone else had access.
• Task titles, descriptions and comments are written by people in your workspace. Torvany tells your AI to treat them as information, not as instructions, but review changes it proposes.
• App names on the approval screen are what the app calls itself. Only approve apps you started connecting yourself.

Limits

• Active connections10 per person (tokens and connected apps together)
• Calls120 a minute per connection
• Changes30 a minute per connection, on top of the call limit
• Status updates6 an hour per person (each one notifies people)
• Comments60 an hour per person (mentions notify people)
• Request size256 KB
• ListsUp to 50 tasks per call; follow next_cursor for more
• Connected appsAccess lasts 1 hour and is refreshed by the app; a connection ends after 90 days without use

For client developers

The endpoint is POST /api/mcp: Streamable HTTP, stateless (no session id, no server-sent events), one JSON-RPC message per request answered with JSON. Supported protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Send Content-Type: application/json.

Authorization follows the MCP authorization spec. A request without a valid token gets 401 with WWW-Authenticate: Bearer resource_metadata="…". Discovery documents:

GET /.well-known/oauth-protected-resource/api/mcp   (RFC 9728)
GET /.well-known/oauth-authorization-server         (RFC 8414)
POST /api/oauth/register                            (RFC 7591, public clients)
GET  /oauth/authorize                               (authorization code + PKCE S256)
POST /api/oauth/token                               (authorization_code, refresh_token)
POST /api/oauth/revoke                              (RFC 7009: sign the app out)

• Scopes: mcp:read and mcp:write. The person may grant less than you ask for; the token response's scope says what was granted.
• Register with token_endpoint_auth_method: "none". Redirect URIs must be https, http on 127.0.0.1 or localhost, or your app's own scheme, and match exactly.
• PKCE with S256 is required. Send resource as the MCP endpoint URL. Codes are single use and expire after 60 seconds.
• Refresh tokens rotate on every use. Retrying with the previous one within 30 seconds (a lost response) still works; using it later ends the connection, so store the newest one.
• Write access is only granted if you ask for mcp:write; the person decides. To sign out, revoke the refresh token at the revocation endpoint.
• Errors on the authorization page are shown to the person, not redirected to your app.
• The server also offers prompts (prompts/list, prompts/get, capability prompts); an unknown prompt or a missing argument gets JSON-RPC error -32602.
• Prompt arguments can be completed (completion/complete, capability completions): workspace slugs this connection can use, project keys and task keys in the chosen workspace, 20 at most. Only what the person could reach with the tools.
• Requests sent from a web page on another origin are refused (403), as the transport spec asks; server-side and desktop clients send no Origin and aren't affected. Repeated invalid tokens from one address get 429 for a while.

Troubleshooting

• 401The token is missing, wrong, revoked or expired, or the account is suspended. Apps that connected by signing in refresh their access automatically; otherwise connect again.
• 403None of the workspaces this connection may use is available right now. The message names each one and why: not on Pro or Business, switched off by its admins, you're a guest there, an owner or admin turned it off for you there, it requires two-factor authentication and yours is off, or it requires single sign-on and the connection was made from a password sign-in. A request sent from a web page on another origin also gets 403.
• 413 / 415The request is larger than 256 KB, or isn't sent as application/json.
• 429More calls a minute than the limit for this connection, or many invalid tokens from your address. Wait for Retry-After.
• Tool errorThe call reached Torvany but couldn't be done, for example a project you can't see ("not found"), a read-only connection trying to change something, an unknown status name, or more changes a minute than allowed. The text says what to fix.