MCP Scoped API Key: Least-Privilege Access for Agents
Configure an MCP scoped API key for Y2, choose read scopes by task, understand workspace boundaries, and distinguish local credentials from remote OAuth.
An MCP scoped API key is a credential with limited permissions used by an MCP integration to access an underlying service. The scope names and enforcement belong to that service. MCP does not define a universal API-key format or a standard set of permissions called OSINT or threat intelligence access.
For Y2's local MCP package, the key is supplied as Y2_API_KEY. Y2 resolves its workspace binding,
checks the requested operation's scopes and entitlements, and enforces the applicable request
limits. Design the credential around the agent's job.
Local API keys and remote MCP authorization
There are two connections to distinguish:
| Connection | Authorization consideration |
|---|---|
| A local host launches Y2's stdio process | The process receives its Y2 credential through protected environment configuration |
| The Y2 process calls Y2's HTTPS API | Y2 validates the bearer key and selected operation |
| A client connects to a protected remote MCP service | Use that service's documented authorization flow |
The MCP authorization specification defines an OAuth-based flow for HTTP transports and separately recommends environment credentials for stdio. A Y2 API key configured for the local package is not a universal OAuth token for arbitrary MCP servers.
For remote services, validate the intended token audience and keep downstream authorization separate. MCP's security guidance prohibits accepting tokens issued for another resource and blindly passing them through. Do not turn a local credentialed process into a public proxy without designing authentication and tenant isolation for that service.
Choose Y2 scopes from the task
These are example starting scopes, not bundled roles:
| Agent task | Starting scope | Boundary to remember |
|---|---|---|
| Read regional OSINT events and source health | osint:read | Covers the documented v1 OSINT operations |
| Research CVEs and cyber graphs | intel:cyber | Use category=cyber when listing incidents |
| Retrieve financial indicators | intel:finint | Does not grant unrelated entity exploration |
| Traverse general entities and relationships | intel:explorer | Broader Intel exploration; assess whether it is necessary |
| Retrieve reports | reports:read | Audio operations have a separate scope |
| Search authorized Global Knowledge | intel:knowledge | Requires a bound workspace and private-beta availability |
The authentication guide and each operation's
x-required-scopes are the authority. Some shared Intel operations accept
alternative scopes and apply category or domain rules. Do not assume a similarly named endpoint
has the same access requirements.
agent:y2 runs Y2's configured agent and can permit account actions through its entitled tools.
It is different from giving an external research agent a few read operations. Grant it only for
an integration designed to use that capability.
Configure the key without putting it in a prompt
Create a key in Developers → API Keys, after selecting the intended
workspace. Use an operational name such as regional-brief-reader and only the scopes that
workflow requires. Eligible workspace owners and admins can create keys on Pro or Elite.
Provide the secret using your host's protected configuration, then launch the documented server:
Y2_API_KEY="$Y2_API_KEY" npx -y @y2-intel/mcpThis command assumes the variable was already supplied securely. It is not an instruction to paste the secret into chat. Protect any client configuration that persists the environment value. See the MCP setup guide for client-specific configuration.
Changing the active workspace in the Y2 interface does not move an existing key. Its stored binding remains the authority for tenant-scoped API requests.
Hiding write tools does not reduce key authority
Y2_MCP_ENABLE_WRITE_TOOLS=false hides dedicated mutation tools. It does not remove permissions
from the API key. The generic y2_call_api tool still uses the selected operation's authorization.
Enforce read-only access by omitting write scopes from the credential itself.
Verify the integration in a controlled test workspace: an allowed read should succeed, while a valid request requiring an omitted scope should be denied. Do not test destructive operations on production resources. Keep keys separate so one integration can be revoked without disrupting every agent using Y2.
Frequently asked questions
Does a 403 mean the API key is invalid?
Not necessarily. The key may lack the required scope, have lost plan eligibility, or fail an IP restriction. Inspect the structured error. Repeating the same unauthorized request will not fix it.
Does key rotation provide an overlap window?
Y2's Regenerate action immediately invalidates the old secret for that record. Plan the consumer update accordingly; use a separate replacement key when an overlap is needed and capacity allows.
Do more keys increase the workspace quota?
No. Y2 applies per-key limits and an aggregate account pool. Separate keys support isolation and operations; they do not multiply the workspace's allowance.
Continue with AI agent security best practices to cover tool results, retained context, and output destinations as well as credentials.