Connect your code (MCP)

Why connect your code

To create tests in Specnote, you connect your AI (Cursor, Claude Code) to Specnote first — that AI is what turns "make a test for this" into a real test in Specnote. On top of that, you can optionally connect your codebase (your GitHub repository), which makes the checking far more accurate.

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 tests and steps far more completely. (A step is a single action, like "enter email → enter password → click Sign Up.")
• Impact analysis becomes possible. When you change one feature, Specnote points out which steps in which tests 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.

Two kinds of connection

This is easy to mix up, so let's be clear — there are two kinds of "connection," and they do different jobs.

• (A) Your AI ↔ Specnote (MCP). This is the bridge that lets the AI coding tool you already use talk to Specnote. It's required to create tests. The channel it uses is MCP (Model Context Protocol) — a standard, secure way for AI tools to talk to outside services.
• (B) Specnote ↔ your GitHub repository. This lets Specnote read your code. It's optional, but connecting it keeps your code up to date automatically, which is the most convenient.

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 before being sent, and aren't stored on our servers.

Secrets are masked before code is sent, and only the masked code goes 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 the sending side 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. 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. 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 something was missed earlier, 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 masking finishes before it reaches the server. The server receives already-masked code and only does one final check.

(A) Connecting your AI — browser authentication or a token

(Tool-by-tool install commands for Claude Code, Cursor, and others are collected in Connect Your AI (Install MCP).)

There are two ways to link your AI tool to Specnote. Pick whichever is easier.

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 — 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 connected, here are the main things you can ask for from inside your AI tool.

Ask for	What it does
Create a test	Drafts a plan review (PRD) and makes tests inside the scope you approved
Send code	Tells you the right path for your situation and sets up what it can
Change impact analysis	Tells you which tests a change affects
Get failure report	When a check fails, lays out where and why it stopped
List and run tests	Pulls up your tests and results, and re-runs verification
Set test accounts / env	Registers test accounts and the site address used for verification
Connect CI	Builds the workflow and token to verify automatically on every push

(B) Connecting your GitHub repository — automatic code freshness

The most convenient way to keep your code up to date is to connect your GitHub repository. Start from the [Connect GitHub] button on the Run tests tab of the workspace board.

1. Install the GitHub App. The button takes you to GitHub's app-install screen. Pick the repository to verify and install it. During install, you'll go through a one-time browser authentication that confirms the install is really yours.
2. Connected. When the install finishes, you return to Specnote and the Run tests tab shows the 3 most recent commits — a sign that it's connected.

This GitHub App is read-only. It only reads your code and repository info; it never edits your code or pushes anything.

The benefit of connecting is that when you create a test or re-check one, Specnote pulls in the latest code on its own, right at that moment. If the code on your default branch changed, it quietly pulls only the changed parts and applies them. You never have to press a "sync" button.

There used to be a mode that auto-sent your code on every commit (a commit hook), but we no longer use it. When GitHub is connected, Specnote checks for the latest automatically when it needs to.

What about code you haven't pushed to GitHub yet?

A GitHub connection only sees code you've pushed. We don't ship a separate program for sending local work-in-progress code.

So it's best to push the code you want verified. From then on, Specnote keeps itself up to date on its own.

You can also just ask your AI to "send the code." It will tell you the right path for your situation and set up whatever it can on your behalf.

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

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

• GitHub won't connect. When installing the app, check that the repository you want to verify is included in the install targets. If you added a new repository, widen the app's access from GitHub's app settings.
• My AI 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 send 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 send onward only the changed parts are sent, finishing in 5–10 seconds.

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