Guide2 min read

What Is an MCP Session?

An MCP session is a short-lived, per-user credential that scopes an agent runtime to one tenant's governed tools — not your workspace API key.

Read the docs →

Guide
TL;DR
  • ›An MCP session is a short-lived credential that lets an agent runtime call Naïve's governed tools over SSE — scoped to one tenant user.
  • ›Your server mints it with sessions.create; the runtime receives mcp.url + Authorization bearer — never your workspace key.
  • ›Default TTL is 15 minutes; maximum 24 hours (per published docs).
  • ›Tools exposed over the session are filtered by the tenant user's Account Kit — same policy as in-process agentTools().
  • ›Revoke the session and the MCP client is rejected immediately — no key rotation required.
  • ›Use sessions for Python, edge, and desktop runtimes; keep nv_sk_live on your trusted backend.

The Model Context Protocol (MCP) lets agent runtimes discover and call tools over a standard wire format. Naïve's MCP session is the credential layer on top: a short-lived, per-user token that exposes governed tools without handing out your workspace API key.

This is the definitional post. For the full architecture narrative, read delegated, revocable MCP sessions for AI agents.

What you get when you mint a session

Your server (trusted)                Untrusted runtime
─────────────────────                ───────────────────
sessions.create({ ttlMs })    →      mcp.url + Bearer nv_sess_…
  for one tenant user                  MCP client connects via SSE
                                       discovers kit-filtered tools

The session binds to exactly one tenant user. The Account Kit on that user decides which tools appear in the MCP catalog.

Minting a session (TypeScript)

import { Naive } from "@usenaive-sdk/server";
const naive = new Naive({ apiKey: process.env.NAIVE_API_KEY! });
 
const client = naive.forUser(tenantUserId);
const session = await client.session({ ttlMs: 15 * 60 * 1000 });
 
// Hand to the runtime — never log the bearer in plaintext
console.log(session.mcp.url);
console.log(session.mcp.headers.Authorization);

Python and other stacks mint the same object over REST against POST /v1/users/:user_id/sessions — see the integration guides.

Session lifecycle

EventWhat happens
CreateNew bearer + SSE endpoint; tools filtered by Account Kit
CallEach tool invocation hits the governance gateway (caps, approvals, audit)
ExpireConnection rejected after TTL (default 15 min, max 24h per published docs)
RevokeImmediate invalidation — see how to revoke access instantly

MCP session vs workspace key

Never embed nv_sk_live in a desktop config, edge worker, or customer-deployed agent. Mint a session per user per run instead. The workspace key stays in your VPC; the runtime gets a credential that dies on its own.

Where to go next

Frequently Asked Questions
What is an MCP session?+
On Naïve, an MCP session is a per-tenant-user credential for the hosted MCP server. Your backend calls sessions.create and receives an SSE URL plus a bearer token (nv_sess_…). The agent runtime connects with that token and discovers governed tools — cards, email, connections, vault — filtered by the user's Account Kit. It is delegated access: scoped, time-limited, revocable.
How is an MCP session different from an API key?+
Your workspace API key (nv_sk_live) authenticates your operator account and must stay on a server you control. An MCP session authenticates one runtime connection for one tenant user, expires automatically, and can be revoked without affecting other customers or sessions. Leaking a session token has a bounded blast radius.
How long does an MCP session last?+
Default TTL is 15 minutes; maximum 24 hours (per published docs). Pass ttl_ms when creating the session. When it expires, the MCP server rejects the connection — no background cleanup required.
What tools does an MCP session expose?+
The same governed toolset as agentTools() in TypeScript — native primitives plus connectable third-party apps — but filtered to what the tenant user's Account Kit allows. A kit that disables cards means the MCP tool list never includes card operations, regardless of what the model asks for.
Can I revoke an MCP session before it expires?+
Yes. sessions.revoke invalidates the token immediately. The next MCP call fails authentication. This is the fastest way to cut off an untrusted runtime without rotating your workspace key or suspending the whole tenant user.
When should I use an MCP session vs agentTools()?+
Use agentTools() when the agent loop runs in your trusted Node backend — lowest latency. Use an MCP session when the runtime is Python, an edge worker, Claude Desktop, Cursor, or any host you do not fully control. Mint the session server-side; hand only the URL and bearer to the runtime.
NT
Naïve Team

Building the agent-native backend.

Keep reading
Delegated, Revocable Access with Per-User MCP Sessions

Per-user MCP sessions give AI agents delegated, revocable access — short-lived, kit-scoped credentials instead of your workspace key. Here's the pattern.

How to Revoke an AI Agent's Access Instantly

How to revoke an AI agent's access instantly: suspend the agent profile or revoke an MCP session so the governance gateway denies all further tool calls.

What Is an AI Agent Identity?

An AI agent identity is the governed record an agent acts as — tenant user, Account Kit, resources, and audit trail — not the model or the API key alone.

Build a Bring-Your-Own-Agent Platform: Hand Each Customer's AI a Scoped, Revocable MCP Session

Build a bring-your-own-agent platform on Naïve: mint each customer a short-lived, revocable MCP session that's scoped and filtered by their Account Kit.