---
title: "MCP Scoped API Key: Least-Privilege Access for Agents"
description: "Configure an MCP scoped API key for Y2, choose read scopes by task, understand workspace boundaries, and distinguish local credentials from remote OAuth."
canonical: https://y2.dev/blog/mcp-scoped-api-key/
---

Written by

Y2 Team

Published

Mon Sep 07 2026

# 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.

[Back](https://y2.dev/blog)

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](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization) 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](https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices) 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](https://y2.dev/docs/api/authentication) and each operation's [`x-required-scopes`](https://y2.dev/api/openapi.yaml) 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](https://y2.dev/app/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/mcp
```

This 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](https://y2.dev/docs/api/mcp) 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](https://y2.dev/blog/ai-agent-security-best-practices) to cover tool results, retained context, and output destinations as well as credentials.