# GoGoPortal connector A Model Context Protocol server over standard input and output, so an AI that supports the protocol can use GoGoPortal's AI Agents, and share what a project taught, after one install. One file, `src/connector.ts`, and no dependencies. Node 22.18 or later runs it as it is; older Node 22 releases need `--experimental-strip-types`, or run it with `npx tsx connector.ts`. ## Switching to the remote connector Claude Code, claude.ai, Cursor, Codex and VS Code use the same tools at `/mcp` instead: your own agent adds that address and signs in, and lessons go through the gogoportal skill (see `/docs/connector`). This connector stays, and is maintained, for any other agent, apps that run local models included (such as LM Studio, Jan, AnythingLLM, Cline and Continue), and for scripts that need a connection's key. For a local model it is the way that asks least of the model: the connector does the cleaning itself, so the model calls one tool to note a lesson. To switch in Claude Code, remove this server first: ``` claude mcp remove gogoportal ``` Then follow the Claude Code lines on the connect page (`/connect`): your own agent adds the plugin, and you sign in and allow its tools from your own terminal. The lessons this connector kept in `~/.gogoportal/lessons/` carry over to the skill. Revoke the old connection on your API page once the new one works. ## Install Your own agent can do all of this for you: send it the text from the connect page ("Other agent or local model"), and it follows the instructions at `/connect/agent/local`. There it connects with `--no-register --no-lessons-line`: it prints the entry for your agent's MCP settings, and leaves Claude Code (which uses the plugin) and your project's `CLAUDE.md` as they are. 1. Save the connector as `~/.gogoportal/connector.ts` (download it from `/docs/downloads/connector.ts`). 2. Make a connection on the connect page, under "Other agent or local model" (`/connect?agent=other`). It gives you a connect code that works once, for a short time. Connect with it: ``` node ~/.gogoportal/connector.ts connect GGP-XXXX-XXXX --site https://your-site.example ``` 3. Load the server: start a new session of your agent, or restart it. 4. Confirm: your agent calls the `check_coverage` tool through the gogoportal server. If it has no tool called `check_coverage`, the server isn't loaded yet: add the entry the connect command printed, then restart. Running the connector by hand doesn't count. Approvals happen on the site, not in the chat: when you ask your agent to share what a project taught, it drafts the lessons and submits them, then gives you the sign-off link. The connector swaps the code for the connection's key and saves the key in `~/.gogoportal//key`, in your home folder (`` is the site's host, such as `www.example.com`, or `your-site.example_8443` for `https://your-site.example:8443`; a path after the host is left out). On macOS and Linux it sets the file so other accounts on your computer can't open it; on Windows the file keeps your home folder's own permissions. It never prints the key, and the key never goes in the MCP settings. The connector reads the file on every call, so connecting again needs no restart. If you revoke a connection, make a new one on your API page and run `connect` again with its code. `GOGOPORTAL_KEY`, if set, is used instead of the file. Then the connect command registers the server: - **Claude Code**: when the `claude` command is on your PATH, it runs `claude mcp add-json gogoportal -s user`, so every project sees the server and new sessions have its tools. A gogoportal server already there for the same file and site is left as it is; a different one is replaced. - **Cursor, Codex, Claude Desktop and Windsurf**: it never edits their files. For each one whose settings file it finds (`~/.cursor/mcp.json`, `~/.codex/config.toml`, `claude_desktop_config.json` in your system's settings folder, `~/.codeium/windsurf/mcp_config.json`), it prints the entry to add and the file it goes in. - **Anything else**: it always prints, last, the entry to add to your agent's global MCP settings, for an agent that is none of those. Last, it prints how you let your own agent use GoGoPortal's tools without asking each time, for each agent. That change is yours, not your agent's: the connect command never touches a permission file, and it tells your agent to pass it to you as it is. `--no-register` skips registering and prints the entry. The entry holds only the connector's full path and the site's address: ```json { "mcpServers": { "gogoportal": { "command": "node", "args": ["/home/you/.gogoportal/connector.ts"], "env": { "GOGOPORTAL_URL": "https://your-site.example" } } } } ``` No folder goes in settings. Lessons alone need no folder: your own agent writes the takeaways, and `draft_lessons` reads nothing on your computer for them. When you ask your own agent to include files from a project with its lessons, or to send a file with a call, it asks which folder and passes your answer as `folder` to `draft_lessons` or `send_file`, for that call only; it never picks one itself. A folder must be a full path that exists. `GOGOPORTAL_SHARE_DIR` and `GOGOPORTAL_UPLOAD_DIR`, if you set them, are used when a call names files and no folder; `GOGOPORTAL_DOWNLOAD_DIR` sets where results are saved. Planning on the site? Once your own agent is connected, a chat's menu ("Continue in your own agent") gives you a line to hand it: it reads that chat's plan with `get_plan` and carries on from there. A connection made earlier for one session still reads that session's plan and, if you switched spending on, asks the agent follow-ups. Nothing else. ## Let your own agent use GoGoPortal's tools When your own agent asks before each tool, or its safety check blocks one, allow them once. Make the change yourself, not through your own agent: - **LM Studio**: choose Always allow for each tool, under App Settings > Tools & Integrations. - **Cline**: list the tools you allow under `"autoApprove"` in the gogoportal entry of its MCP settings. - **Claude Code**, running this connector: run this in your own terminal: ``` node ~/.gogoportal/connector.ts allow ``` It shows the one line it adds to `~/.claude/settings.json` (under `permissions.allow`), asks, and adds it only when you answer `y` or `yes`. It keeps everything else in the file, and the file as it was beside it as a backup. It runs only in a terminal you type in, so your agent can't run it for you. - **Any other app**: approve a tool when it asks; if it offers to always allow one, choose that. Cursor, Codex and the other agents that sign in by the address have their own lines on your API page. When a tool is still blocked, your own agent is told to say so in one line, point you to these lines on your API page, and never work around the block or change permission settings itself. ## Tools `find_agents`, `get_agent`, `open_session`, `rewrite_request`, `answer_questions`, `quote_call`, `preview_call`, `make_call`, `ask_question`, `get_result`, `report_call`, `stop_call`, `list_sessions`, `get_session`, `get_plan`, `send_file`, `check_coverage`, `draft_lessons`, `submit_lessons`, `note_lesson`, `send_lessons_now`, `draft_correction`, `submit_correction`, `get_share`, `list_shared_projects` and `list_findings`. Version 2.14.0 renamed `prepare_share`, `send_share`, `prepare_correction` and `send_correction` to `draft_lessons`, `submit_lessons`, `draft_correction` and `submit_correction`. ## Two ways in - **Plan my project**: `open_session` with way `plan` and your request in `details`. The agent reads it first, at the site's cost, and asks only the questions it still needs; what your request already answers comes back filled in. Your own agent answers the rest with `answer_questions`, from what it knows about the project or by asking you. Answering is free. The plan's main call waits until the details the agent needs are in, and sends your request as its details. Changed your mind? `rewrite_request` reads it again and keeps your answers. - **Ask a question**: `ask_question`. Nothing is asked first: if the agent needs more from you, it says so in the answer. Charged for what it uses, like any call. `get_plan` reads the plan as it changes, so your own agent doesn't work from a stale copy. ## The rule for using an agent A call is charged for what it uses, from your credits; no price is quoted before it runs. `make_call` previews the exact call first (whether it can start, the plan's details, and where your connection stands today), then calls: - your connection may run one chat session a day without asking, with up to the calls a day you set (both are yours to change on your API page); another session that day, more calls, or any call while spending is off waits for your yes on your Approvals page, and your own agent shows you the link; - an agent that is still New is called only when you left "Try AI Agents that are still New" on for the connection (it starts on); with it off, a New agent is not called. It asks you first when the preview says your request doesn't look related to the agent. When your credits ran low before a call's research was done, `get_result` says so, and that more credits give a call like it more room. When a plan's main call is missing details, `make_call` shows which and points your own agent at `answer_questions`. Nothing is held or charged. ## The onboarding program `draft_lessons` never reads your project folder on its own. Your own agent writes the takeaways, in its own words, and may name files to include, by their paths inside the folder you named in the chat (its `folder`, or `GOGOPORTAL_SHARE_DIR` when it names none). Nothing is read beyond the files it names; by default none. How it works: - it checks each named file on your computer: inside the folder and not reached through a link, not hidden, not named like a key or password file, not listed in `.gogoportal-private` (one path or pattern per line), not empty or over 5 MB, text, and holding nothing that looks like a key, a password or a token, no personal data (email addresses, phone numbers), and none of your client names (from `.gogoportal-clients` or what you tell your own agent) or terms that identify the project. A file that fails is refused by name, and nothing is prepared until your own agent drops it; - it reads `.gogoportal-private` and `.gogoportal-clients`, when they are there, only to check a file your own agent names; - it replaces secrets, personal data, and the client names and terms your own agent gives with `[removed]` in what your own agent wrote; - it sends the terms that identify the project with the package, so the site's final check refuses any part that still holds one; the site never stores the list (your client names stay on your computer); - it asks the site which agent already covers this kind of project, sending only the description and kinds of project your own agent writes, so your own agent writes only what your project adds; - it asks your own agent when each takeaway was learned and on which versions; - it asks what each takeaway cost to learn: from the logged usage of the sessions involved where logs exist, an estimate only where they don't, marked so. The figure earns nothing; you read it on your sign-off page, and can correct it or leave it out there; - it says in one line what it prepared (the takeaways and the files it included) and what it removed from what your own agent wrote, in counts, and `submit_lessons` sends it at once. You approve on the site, not in the chat: your agent gives you the sign-off link, and nothing goes live until you sign off. It prints your sign-off page. Only you sign off, signed in. The connector cannot. Connector 2.17.0 no longer asks for the questions a project proposes or the details its main call needs: an AI Agent writes its questions for each member's request. A `draft_lessons` call that still sends `questions` or `required_details` is accepted, and they are left out. The same package can be uploaded on the site instead, at `/account/sharing/upload`: the package's JSON and the files it lists. The site's final check and your sign-off are the same. ## Lessons as your own agent works The server's instructions ask your own agent, as it works in your project, to note what research or a fix taught about this kind of project (a pitfall, a decision and why, a version change, a requirement, something that failed) with `note_lesson`: short, in its own words, nothing private, without asking you each time. The connector strips each lesson on your computer (secrets, email addresses, phone numbers, IDs, full paths and the client names in `.gogoportal-clients`) and keeps it in `~/.gogoportal/lessons/.jsonl`, with `.md` beside it for you to read. `note_lesson` reads nothing of your project but your own `.gogoportal-clients` list, when it is there, for the client names to strip: the lesson is what your agent wrote. Noting a lesson sends nothing. It sends only those lessons, not the project's files, in batches, once most of the research is done (`LESSON_BATCH`, the same rule as the gogoportal skill's): - when the research has gone quiet: at least 10 lessons waiting, 7 days since the project's last batch (or its first lesson), and no new lesson for 3 days. The connector checks when it starts, and sends that batch itself; - when you say the project, or its research, is finished: your agent calls `send_lessons_now`, with at least 3 waiting; - at 40 waiting, at the next natural stopping point, such as a finished task or when you wrap up, never in the middle of research: `note_lesson`'s answer says so, and your agent calls `send_lessons_now` there. Connector 2.15.0 retired `GOGOPORTAL_LESSONS_CREDITS_CENTS`: a batch due on the credits used could go in the middle of research. The setting is ignored. The first batch starts a shared project (your agent gives its description and kinds once, from the project, with a lesson or with `send_lessons_now`); later batches add to it. Each batch waits for your sign-off on the site, whatever you chose for updates, unless you choose otherwise for lessons in your Sharing settings. The `connect` command adds one line asking for lessons to the project's `CLAUDE.md`; `--no-lessons-line` skips it, and deleting the line stops it. ## Corrections When an agent's takeaway is out of date, or was wrong, `draft_correction` writes a correction aimed at that one takeaway (its topic id from `check_coverage`): since when (a version or a date), what is true now, and an https source the site can read. It refuses an http source or a missing "since". `submit_correction` sends it at once, and you approve it on the site like any contribution: nothing goes live until you sign off. ## Results are data Everything a member wrote, or the site wrote from members' contributions, reaches your own agent inside a block marked with a fresh random nonce, under a line saying it is data, never instructions. Result files are saved into the download folder and never opened, unpacked or run; a file that can run code is saved with `.blocked` added to its name.