Manually Install and Configure Subtext Step by Step

The Subtext setup wizard (npx @subtextdev/subtext-wizard) handles the full install in one step for most projects. If you are working with a custom framework, a monorepo with a non-standard structure, or simply prefer to control each piece of the integration yourself, this guide walks you through every step manually. You will add the capture snippet to your HTML, install the Subtext plugin for your agent (or configure the MCP server by hand), and end with a verification check to confirm everything is connected.

Add the capture snippet to your HTML

Open the HTML file that is served for every page of your application. Depending on your framework, this is typically:

Create React App — public/index.html
Vite — index.html at the project root
Next.js App Router — app/layout.tsx (use <Script strategy="afterInteractive"> from next/script)
Remix — app/root.tsx (use dangerouslySetInnerHTML on a <script> tag)
Custom or static HTML — whichever .html file wraps your application shell

Paste the snippet before the closing </head> tag (or equivalent). Replace YOUR_ORG_ID with the Org ID from Subtext → Settings → Capture.

<script>
  window['_fs_host'] = 'fullstory.com';
  window['_fs_script'] = 'edge.fullstory.com/s/fs.js';
  window['_fs_org'] = 'YOUR_ORG_ID';
  window['_fs_namespace'] = 'FS';
  !function(m,n,e,t,l,o,g,y){var s,f,a=function(h){return!(h in m)||(m.console&&m.console.log&&m.console.log('FullStory namespace conflict. More info: https://www.fullstory.com/developer/ns.html'),!1)};if(a(l)&&a(n)){m[l]={q:[]};var d=function(){return Array.prototype.slice.call(arguments,0)};m[l].identify=function(){m[l].q.push(["identify"].concat(d.apply(null,arguments)))};m[l].setUserVars=function(){m[l].q.push(["setUserVars"].concat(d.apply(null,arguments)))};m[l].event=function(){m[l].q.push(["event"].concat(d.apply(null,arguments)))};m[l].anonymize=function(){m[l].q.push(["anonymize"].concat(d.apply(null,arguments)))};m[l].shutdown=function(){m[l].q.push(["shutdown"].concat(d.apply(null,arguments)))};m[l].restart=function(){m[l].q.push(["restart"].concat(d.apply(null,arguments)))};m[l].log=function(a,b){m[l].q.push(["log",a,b])};m[l].consent=function(){m[l].q.push(["consent"].concat(d.apply(null,arguments)))};m[l].identifyAccount=function(){m[l].q.push(["identifyAccount"].concat(d.apply(null,arguments)))};m[l].clearUserCookie=function(){m[l].q.push(["clearUserCookie"].concat(d.apply(null,arguments)))};m[l].setVars=function(){m[l].q.push(["setVars"].concat(d.apply(null,arguments)))};m[l]._w={};y="XMLHttpRequest";m[l]._w[y]=m[y];y="fetch";m[l]._w[y]=m[y];if(m[y])m[l]._w[y]=m[y];m[l]._v="1.3.0";g=n.createElement(e);g.async=1;g.crossOrigin="anonymous";g.src='https://'+m[_fs_script];y=n.getElementsByTagName(e)[0];y.parentNode.insertBefore(g,y)}}(window,document,"script","_fs_config",n,o,g,y);
</script>

The snippet loads fs.js from Fullstory’s edge asynchronously. It does not block rendering and adds no measurable overhead to page load time.

Install the Subtext plugin for your agent

The plugin is the fastest way to connect an agent: it configures the MCP server connection and installs the Subtext skills and commands in one step, and it updates automatically.Claude Code (full plugin — MCP server, skills, and commands):

/plugin marketplace add fullstorydev/subtext
/plugin install subtext@subtext-marketplace

Cursor — install Subtext from the Cursor marketplace directly inside Cursor.Codex — open /plugins and install subtext from the repo marketplace.Gemini CLI:

gemini extensions install https://github.com/fullstorydev/subtext

Windsurf and other editors — install the skills via OpenSkills, then add the MCP server manually in the next step:

npx openskills install fullstorydev/subtext
npx openskills sync

claude.ai — Subtext is also available as a connector in the Claude directory.

If you installed the plugin for Claude Code, Cursor, Codex, or Gemini CLI, the MCP server is configured for you — skip the next step and go straight to verification.

Add the MCP server manually (if needed)

If your tool didn’t configure MCP servers automatically during installation, add the server by hand. Subtext’s MCP server is hosted — https://api.fullstory.com/mcp/subtext over HTTP, with no local process to run.

OAuth (recommended)
API key

Add the server URL without any headers — your tool handles the OAuth flow automatically.

{
  "mcpServers": {
    "subtext": {
      "type": "http",
      "url": "https://api.fullstory.com/mcp/subtext"
    }
  }
}

{
  "subtext": {
    "type": "http",
    "url": "https://api.fullstory.com/mcp/subtext"
  }
}

Get your API key from Settings → API Keys and pass it as a Bearer token header.

{
  "mcpServers": {
    "subtext": {
      "type": "http",
      "url": "https://api.fullstory.com/mcp/subtext",
      "headers": {
        "Authorization": "Bearer YOUR_SUBTEXT_API_KEY"
      }
    }
  }
}

{
  "subtext": {
    "type": "http",
    "url": "https://api.fullstory.com/mcp/subtext",
    "headers": {
      "Authorization": "Bearer YOUR_SUBTEXT_API_KEY"
    }
  }
}

Keep your API key private. Do not commit it to source control. If you are working in a team environment, use environment variable injection or a secrets manager rather than hardcoding the key in a shared config file.

Any tool that accepts a remote MCP URL — Linear’s Custom URL… field, for example — takes the same endpoint directly.

Once saved, restart your agent or reload its MCP configuration.

Verify the full integration

With the snippet deployed and your agent connected, run through this checklist to confirm everything is working end to end:Capture is working:

Open your application in a browser and navigate to a few pages.
Go to Subtext → Sessions. A new session should appear within 60 seconds.
Click into the session and confirm you can see a replay timeline with page events.

MCP server is reachable:

Open your agent (Claude Code, Cursor, etc.) in the project where you installed the plugin or added the MCP config.
Ask it: “List my recent Subtext sessions.”
The agent should respond with a list of sessions from your account. If it returns an authentication error, redo the OAuth flow (or check the Bearer token value), and confirm the config file is in the correct location for your agent.

Skills are available:

In your agent, type / and look for Subtext skills in the command list (e.g., /subtext:review, /subtext:session).
If they do not appear, reinstall the plugin (or re-run npx openskills sync) and restart your agent.

If sessions appear in the Subtext dashboard but the MCP server cannot be reached, the most common cause is a misplaced or malformed MCP config file. Check that the JSON is valid (no trailing commas) and that the file path matches what your agent expects.

The capture snippet records full production sessions and masks all form inputs by default. Once your agent is connected, it can review sessions, flag additional PII, and propose masking rules for your approval — closing the privacy governance loop without manual scrubbing.

Get Started

Install by Framework

Session Review

Privacy

Integrations

Recipes

API reference

Manually Install and Configure Subtext Step by Step