Connect your code (MCP)

Why connect your code

You can use Specnote without connecting your code at all. Just give it your site address, and the AI will click through your screens like a real person to build and run scenarios. So feel free to start without a connection at first.

That said, connecting your code makes three things noticeably stronger.

• Extraction gets more accurate. Instead of looking only at how a screen appears, the AI reads your actual code structure — so it maps out scenarios and steps far more completely. (A step is a single action in a scenario, like "enter email → enter password → click Sign Up.")
• Impact analysis becomes possible. When you change one feature, Specnote points out which steps in which scenarios are affected. You can gauge in advance what might break with this change.
• Re-verification gets smarter. It re-checks only the parts of the code that changed, so you don't have to verify everything from scratch every time.

Connecting is how you link Specnote to AI coding tools like Claude Code or Cursor. The bridge it uses is called MCP (Model Context Protocol) — think of it as a standard, secure channel that lets AI tools talk to outside services.

Our security promise, up front

When people hear "connect your code," the first worry is usually: "Wait, does my password or payment key get sent too?" So let's settle that right away.

Your production secrets are masked on your own computer first, and aren't stored on our servers.

Secrets are masked on your own computer first, and only the masked code is sent to the server. The server then runs a safety-net pass to catch anything that slipped through.

Production secrets are the real keys that run your live service — your production database password, payment keys, external service access keys, and so on. Masking looks for known patterns, so it can't promise 100%. The safest habit is to never hard-code production secrets in your code — and even if one slips through, it's filtered once on your PC and once more on the server.

What we receive · what we don't

Here's what does and doesn't travel when you connect.

What we receive	What we don't receive
Screen code (frontend — what users see)	Secret files like .env · *.key · *.pem
Server code (backend API — what runs behind the screen)	External service keys like AWS · OpenAI · Google
Code structure analysis (which screens connect to which features)	Payment keys · database passwords · production environment variables

What we receive is only the code and structure needed to understand "what this app looks like and how it behaves." Values like passwords and keys are not received.

Three layers that protect your secrets

Three layers keep secrets from leaking. If one layer misses something, the next one catches it.

1. Layer 1 — secret files are excluded on your PC. Secret files like .env·*.key·*.pem, and any file listed in .gitignore, are never read in the first place. The file is dropped from the candidate list entirely.
2. Layer 2 — secrets inside code are masked on your PC. Even if a key was accidentally written into the code, 14 secret patterns (external service keys, payment keys, database connection details, auth tokens, and more) are found and replaced with a masked placeholder before anything is sent.
3. Layer 3 — the server checks once more. In case your PC missed something, the server runs a safety-net pass to mask any remaining secrets. If it catches anything extra, it tells you "we masked this much more."

The key point is that all masking finishes on your PC first. The server receives already-masked code and only does one final check.

Connecting — token or browser authentication

There are two ways to connect. Pick whichever is easier for you.

Option A — Browser authentication (recommended). In an AI tool like Claude Code, you click "Allow" just once and you're done. There's no token to copy or handle yourself. Once allowed, it rotates automatically (renews itself safely on a schedule) for 30 days, so you don't have to re-authenticate during that time. It's the easiest option if you'd rather not think about tokens, which is why we recommend it.

Option B — Sync token. You issue a token from My Page and use it. This token starts with spnt_ and doesn't expire on its own — it stays valid until you revoke it from My Page. It carries read, push, and test-run permissions, so it's a good fit for automated environments like CI. Treat this token like a password, though — don't commit it to git or share it, and if it leaks, revoke it from My Page right away.

Once you have a token, a tool called specnote-sync lets you send your code in a single line. There's nothing extra to install (Node 18 or higher is all you need) — just run the line below in your terminal.

npx @specnote/sync sync-all --base-url https://specnote.io --spec-id <PROJECT ID> --pat <TOKEN>

After connecting, here are the main things you can do from inside your AI coding tool.

Feature	What it does
Send code (specnote_sync_code)	Sends your masked code in full
Send API list (specnote_sync_api)	Sends your server feature list
Change impact analysis (specnote_analyze_change)	Tells you which scenarios a change affects
AI auto-extraction (specnote_run_ai_agent_extraction)	Has the AI explore your app to find scenario candidates
Get failure report (specnote_get_failure_report)	When a check fails, lays out where and why it stopped
List scenarios (list_scenarios)	Pulls up the scenarios you made and their results
Set test accounts and environment (specnote_upsert_test_account, specnote_upsert_test_environment)	Registers test accounts and environment settings used for verification

Code sync is one-way. Your PC only sends code to Specnote. Specnote never changes your code in return. That's why you can connect with confidence.

The first sync takes about 30–60 seconds for 100 files. After that, only the changed parts are sent, so it usually finishes in 5–10 seconds.

Test-only secrets

Verification often needs a login. But you never have to enter a production password for that. Instead, you register test-only secrets separately — things like a test account or a sandbox (a practice fake-payment environment) key, values that cause no real harm even if leaked.

Registered values are encrypted immediately (we use a dedicated vault called KMS). Only you can open them, and even when you click "Reveal" on screen, the value shows for just 5 seconds and then hides again. They're kept completely separate from production secrets, so you can safely enter only the minimum values your tests need.

Where people often get stuck

• It won't connect. If you're using browser authentication, re-authenticate by clicking "Allow" again in your AI tool. If you're using a token, check that it hasn't been revoked in My Page, and issue a fresh one if needed.
• Sync is too slow. The first sync genuinely takes 30–60 seconds. If it stays slow after that, check whether you're sending an unusually large number of files. Normally, from the second sync onward only the changed parts are sent, finishing in 5–10 seconds.

For more, see the FAQ, or email support@specnote.io.