# Connect Trayo to this agent Trayo tracks companies (accounts), finds events at them that match the signals you define, finds new companies and people, looks up emails and phones, and researches a company or a person. This file tells you, the agent, how to connect it. ## Start here If `trayo_*` tools are already in your tool list, Trayo is already connected: do not install it again. Go straight to **After Trayo is connected**. Otherwise, everything below connects one thing: the Trayo MCP server at `https://api.trayo.ai/v1/mcp` (streamable HTTP). The user signs in to Trayo in their browser and chooses the workspace. Find the section for the client you are running in, follow only that section, then **After Trayo is connected**. Never relay another client's steps to the user: they will not work in yours. If you are not sure which client you are in, ask the user. - Claude Code - Codex - Cursor - Claude.ai, Claude Desktop and Cowork - ChatGPT - Any other MCP client Rules for every step: - The user signs in themselves, in their browser. Never ask for a password or a sign-in code in the conversation. - Never ask the user to paste an API key into the conversation. A key goes only into the client's own masked secret field or secret file. - Ask before changing any permission setting. The default answer is No. ## Claude Code ### Step 1. Connect the Trayo MCP server Run `claude mcp add --transport http --scope user trayo https://api.trayo.ai/v1/mcp`. Sign-in is OAuth: no key is stored on the machine. If the user prefers the Trayo plugin (the same tools plus twelve task skills), run `claude plugin marketplace add trayoai/trayo-plugin` and `claude plugin install trayo@trayo-plugins` instead. The plugin signs in with OAuth too, so step 2 still applies. Use one of the two, not both. If the user already added the Trayo plugin in Claude on the web or desktop and signs in to Claude Code with that same account, it syncs into Claude Code when Claude Code starts: do not install anything. Tell them to run `/reload-plugins`, then go to step 2. ### Step 2. Sign in - **If you installed the plugin in this session, or it synced from Claude:** tell the user to run `/reload-plugins`, then `/mcp`, select **trayo** and choose **Authenticate**. A browser tab opens for the sign-in. Wait until they say it is done. If **trayo** is not in the menu, continue as for `claude mcp add` below. - **If you ran `claude mcp add` in this session:** the `/mcp` menu lists only the servers registered when the session started, so **trayo** is not in it yet. Tell the user to start a new session and say: "Continue Trayo setup from https://api.trayo.ai/agent-install.txt, section Claude Code, step 2". In the Claude desktop app, also give them this link, which opens that session with the sentence typed in: claude://code/new?q=Continue%20Trayo%20setup%20from%20https%3A%2F%2Fapi.trayo.ai%2Fagent-install.txt%2C%20section%20Claude%20Code%2C%20step%202. Stop here until then. - **If you were started with that sentence:** tell the user to run `/mcp`, select **trayo** and choose **Authenticate**. A browser tab opens for the sign-in. Wait until they say it is done. If the `trayo_*` tools are not in your tool list, tell the user to start a new session and say: "Continue Trayo setup from https://api.trayo.ai/agent-install.txt, section After Trayo is connected, step 1: tell me briefly what Trayo does, confirm my workspace with trayo_whoami, then suggest a few things to start with". Stop here until then. ### Step 3. Offer to skip the approval prompts Ask the user: "Allow Trayo tools to run without asking each time? [y/N]". Contact lookups use the workspace's lookup allowance, so say that when you ask. Only on an explicit yes, add `mcp__trayo` (or `mcp__plugin_trayo_trayo` for the plugin) to `permissions.allow` in `~/.claude/settings.json`, keeping every other entry. Then go to **After Trayo is connected**. ## Codex ### Step 1. Install the Trayo plugin and sign in Run `codex plugin marketplace add trayoai/trayo-plugin && codex plugin add trayo@trayo-plugins`. The plugin brings the Trayo MCP server and twelve task skills. Then tell the user a browser tab will open, and run `codex mcp login trayo`. Wait until they say the sign-in is done. If the plugin install fails, run `codex mcp add trayo --url https://api.trayo.ai/v1/mcp` instead: the same tools, without the skills. Then sign in the same way. ### Step 2. Load the tools Codex loads a new MCP server only in a new session. If the `trayo_*` tools are not in your tool list, tell the user to start a new session and say: "Continue Trayo setup from https://api.trayo.ai/agent-install.txt, section After Trayo is connected, step 1: tell me briefly what Trayo does, confirm my workspace with trayo_whoami, then suggest a few things to start with". In the Codex app, also give them this link, which opens that session with the sentence typed in: codex://threads/new?prompt=Continue%20Trayo%20setup%20from%20https%3A%2F%2Fapi.trayo.ai%2Fagent-install.txt%2C%20section%20After%20Trayo%20is%20connected%2C%20step%201%3A%20tell%20me%20briefly%20what%20Trayo%20does%2C%20confirm%20my%20workspace%20with%20trayo_whoami%2C%20then%20suggest%20a%20few%20things%20to%20start%20with Stop here until then. Then go to **After Trayo is connected**. ## Cursor ### Step 1. Connect the Trayo MCP server and sign in Give the user this link. It opens Cursor's MCP install dialog with Trayo filled in: cursor://anysphere.cursor-deeplink/mcp/install?name=trayo&config=eyJ1cmwiOiJodHRwczovL2FwaS50cmF5by5haS92MS9tY3AifQ%3D%3D If the link does not open, add `"trayo": { "url": "https://api.trayo.ai/v1/mcp" }` under `mcpServers` in `~/.cursor/mcp.json` yourself, keeping every other entry. Then the user opens **Customize** in Cursor's sidebar, finds **trayo** under MCP servers, connects it and signs in in the browser tab that opens. Wait until they say it is done. ### Step 2. Load the tools If the `trayo_*` tools are not in your tool list, tell the user to start a new chat and say: "Continue Trayo setup from https://api.trayo.ai/agent-install.txt, section After Trayo is connected, step 1: tell me briefly what Trayo does, confirm my workspace with trayo_whoami, then suggest a few things to start with". Stop here until then. Then go to **After Trayo is connected**. ## Claude.ai, Claude Desktop and Cowork ### Step 1. Have the user add the Trayo plugin You cannot add a plugin or connector from the conversation, even with a code sandbox: it runs in the cloud, not on the user's machine. The plugin is saved to the user's Claude account, so one install covers chat on the web, desktop and mobile, Cowork, and Claude Code signed in with that account. Give the user this link. It opens the Trayo plugin's Connectors page in Claude: https://claude.ai/customize/plugins/yours/id/plugin_01C3iBsnpNo3U5fQT9QbhhUa/connectors They select **Add** to install the plugin, then **Connect** on **trayo** and sign in. Adding the plugin does not sign them in by itself. If the link does not open, they go to Customize → Plugins → Add → Add marketplace, enter `trayoai/trayo-plugin`, and install **Trayo** there. Plugins need a Pro, Max, Team or Enterprise plan. On the Free plan, or if they want only the tools, give them this link instead. It opens Claude's add-connector dialog with Trayo and its URL filled in: https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Trayo&connectorUrl=https%3A%2F%2Fapi.trayo.ai%2Fv1%2Fmcp They confirm it, connect it and sign in. If the link does not open, they add a custom connector named **Trayo** with the URL `https://api.trayo.ai/v1/mcp` in Customize → Connectors. On a Team or Enterprise plan only an Owner can add a custom connector, in Organization settings → Connectors; members then connect it. Wait until they say it is done. ### Step 2. Load the tools If the `trayo_*` tools are not in your tool list, tell the user to start a new conversation and say: "Continue Trayo setup from https://api.trayo.ai/agent-install.txt, section After Trayo is connected, step 1: tell me briefly what Trayo does, confirm my workspace with trayo_whoami, then suggest a few things to start with". Stop here until then. Then go to **After Trayo is connected**. ## ChatGPT ### Step 1. Have the user add the Trayo app You cannot add an app from the conversation. Developer mode is needed, on the web, and not every plan has it (on a work plan an admin may have to allow it). Tell the user to turn on developer mode in ChatGPT's settings, then create an app named **Trayo** with the URL `https://api.trayo.ai/v1/mcp` and OAuth authentication. Client ID and client secret stay empty. They connect it and sign in, then pick Trayo from **+ → Developer mode** in a chat. Wait until they say it is done. ### Step 2. Load the tools If the `trayo_*` tools are not in your tool list, tell the user to start a new conversation and say: "Continue Trayo setup from https://api.trayo.ai/agent-install.txt, section After Trayo is connected, step 1: tell me briefly what Trayo does, confirm my workspace with trayo_whoami, then suggest a few things to start with". Stop here until then. Then go to **After Trayo is connected**. ## Any other MCP client ### Step 1. Connect the Trayo MCP server Add a streamable HTTP server named **trayo** with the URL `https://api.trayo.ai/v1/mcp`. Use OAuth if the client supports it. Otherwise the user sets the header `Authorization: Bearer ` in the client's own settings, with a key from the **API keys** page of the Trayo web app. Wait until they say it is done. If the client reads skills (`SKILL.md` folders), also install the Trayo skills from https://github.com/trayoai/trayo-plugin/tree/main/trayo/skills. They teach you the Trayo workflows. Ask the user before adding them. ### Step 2. Load the tools Some clients load a new MCP server only in a new session. If the `trayo_*` tools are not in your tool list, tell the user to start a new session and say: "Continue Trayo setup from https://api.trayo.ai/agent-install.txt, section After Trayo is connected, step 1: tell me briefly what Trayo does, confirm my workspace with trayo_whoami, then suggest a few things to start with". Stop here until then. Then go to **After Trayo is connected**. ## After Trayo is connected ### Step 1. Confirm the connection Open with one or two sentences on what Trayo does for the user, from the top of this file. Then call `trayo_whoami`. Tell the user the workspace name and plan, and confirm it is the workspace they meant. If it is the wrong one, they reconnect and choose the workspace again at sign-in. Refer to the workspace by name; do not ask the user for an id. ### Step 2. Review the saved onboarding assumptions with the user An API-signup workspace usually has generated solutions, buyer personas, an ICP profile and signals, but no starter accounts or first discovery. Those generated assumptions are a draft, not facts the user has approved. Call `trayo_get_workspace`, `trayo_list_signals`, `trayo_list_accounts` and `trayo_list_events`. Show one compact draft: what the company sells, who buys it, the buyer thesis/geography/size, the signals it watches, and existing account/event counts. Do not claim there are no accounts or events without checking; zero events does not prove no discovery run occurred. Ask one open question about what is wrong or missing; save extra recommendations for after that answer. Do not rewrite anything merely because it was generated. The ICP is the exception, and `buyerProfileSource` says which case you are in. `saved` is onboarding's own profile: show it as the draft above. `inferred` means nothing usable was saved and what you got back is a generic placeholder, not this workspace — do not present its buyer thesis, geography or size as the company's. Say no ICP has been saved yet, and ask the user for those three before anything relies on them. `partial` means someone has already supplied some ICP fields through this API and the rest are still that placeholder: treat the supplied ones as the user's and keep confirming the rest. `unreadable` means an ICP is saved but this API cannot read or patch it — say so and leave it to the Trayo app rather than asking the user to re-enter it. When the user corrects it, preview only the proposed changes and confirm them before saving. Use `trayo_set_workspace` with only the agreed fields: `solutionItems` and `stakeholderPersonas` replace their respective complete lists, so carry forward unchanged entries and pass the latest workspace `revision` as `expectedRevision`. On a conflict, re-read and merge instead of retrying a stale list. A changed solution list clears the old `solutionsBrief` unless you send a new one. Do not re-send an old brief verbatim if it may be inaccurate after the edit; omit it and let it clear unless the user approves a new accurate one. `buyerProfile` patches only named ICP fields, including nested geography and sizeBand. Use `trayo_update_signal` for a changed signal, `trayo_create_signal` for a new one, and `trayo_delete_signal` only when the user explicitly wants one removed. You can use the prose fields for a workspace without structured cards. Re-read the settings and signals to confirm the saved result. Corrections steer future work, not old events. Then continue from what exists: - **There are events:** show the three most recent: company, what happened, and matching signal. - **There are accounts and signals but no events:** ask whether to run discovery on those accounts. - **There are signals but no accounts:** offer to find and import a small, user-approved starter cohort, then run discovery. API signup deliberately stops before this step. - **There are no signals:** ask what the user wants tracked, save one or two agreed signals, then continue with accounts. If an installed Trayo `onboard-workspace` skill supports reviewing and revising a populated workspace, you may use it to guide these steps. Older versions assume an empty workspace; in that case, follow this guide with the MCP tools instead. Change nothing the user did not ask for. ### Step 3. Hand over Setup is complete after this step. Tell the user in one line what they can now do, and propose three things you could do for them right now. Base them on what you actually found: name a real account or event only if one exists. For a new API-signup workspace with no accounts, offer to review its buyer profile, curate a small starter cohort, or scan that approved cohort for one of its saved signals. For a workspace with events, you could instead: - Research the company behind one of the events you showed, and the people there who would buy. - Find companies like their active accounts. - Find the right people and their emails at an account that has a recent event. Offer to run one. Report setup details only when the user must act on them. REST API reference for scripts and integrations: https://api.trayo.ai/llms.txt