> For the complete documentation index, see [llms.txt](https://docs.dorg.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dorg.pro/create-competency/develop-a-competency/mcp-server/injected-parameters.md).

# Injected parameters

## Orchestrator-Injected Context

When the Dorg orchestrator calls a tool on your MCP server, it can automatically inject context variables (user identity, tenant info, tokens, etc.) directly into the tool arguments **before** the call reaches your server. The LLM never sees these values and can never supply or tamper with them.

This document explains what variables are available, how to declare them in your manifest, and how to receive them in your server code.

***

### How injection works

1. You declare `injected_params` for each tool in `competency.manifest.json`.
2. When the orchestrator installs your competency, the customer sees the declared keys and explicitly consents to sharing that data with your server.
3. On every `tools/call`, the orchestrator resolves each declared key and merges the values into `params.arguments` before forwarding the JSON-RPC request to your MCP endpoint.
4. The injected keys are **stripped from the tool's `inputSchema`** so the LLM never includes them, and any attempt by the LLM to supply a protected key is detected and blocked by the orchestrator.

Your server reads the injected values from `params.arguments` exactly like any other argument — no special headers or middleware needed.

***

### Available context keys

#### User context

Resolved from the authenticated `ClaimsPrincipal` of the colleague talking to the dorg.

| Key                 | Type       | Description                              |
| ------------------- | ---------- | ---------------------------------------- |
| `user_email`        | `string`   | Email address of the colleague           |
| `user_azure_id`     | `string`   | Azure AD object ID (`oid` claim)         |
| `user_display_name` | `string`   | Display name (`name` claim)              |
| `user_groups`       | `string[]` | Azure AD groups the colleague belongs to |

#### Conversation context

Propagated from the active channel (Teams, email, web, …).

| Key               | Type     | Description                              |
| ----------------- | -------- | ---------------------------------------- |
| `channel`         | `string` | Channel type: `teams`, `email`, `web`, … |
| `message_id`      | `string` | ID of the current inbound message        |
| `conversation_id` | `string` | ID of the current conversation           |

#### Tenant / dorg context

Static values from the orchestrator's configuration.

| Key             | Type     | Description                                        |
| --------------- | -------- | -------------------------------------------------- |
| `tenant_id`     | `string` | Azure AD tenant ID of the customer                 |
| `dorg_azure_id` | `string` | Azure AD object ID of the dorg itself              |
| `dorg_name`     | `string` | Name of this dorg instance                         |
| `dorg_version`  | `string` | Running orchestrator version                       |
| `env`           | `string` | Execution environment: `prod`, `staging`, or `dev` |

#### Delegated Microsoft Graph token

| Key             | Type     | Scope support | Description                                                                                                                                                                                                                                         |
| --------------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `msgraph_token` | `string` | Yes           | An access token for Microsoft Graph delegated to the **dorg's own Azure AD identity** (not the end-user's). You must declare the required scopes in the manifest; they must be a subset of what the dorg app registration is configured to request. |

{% hint style="warning" %}
**Important:** this token is delegated to the dorg's identity, not the end-user's. Use it to call MS Graph APIs as the dorg (e.g. read shared mailboxes, SharePoint sites the dorg has access to). Do not assume it grants access to the user's personal resources.
{% endhint %}

#### AI / LLM secrets

Static secrets owned by the dorg — useful if your competency needs to call an LLM.

| Key                   | Type             | Description                             |
| --------------------- | ---------------- | --------------------------------------- |
| `anthropic_api_key`   | `string`         | Anthropic API key                       |
| `ai_foundry_endpoint` | `string`         | Azure AI Foundry endpoint URL           |
| `ai_foundry_key`      | `string`         | Azure AI Foundry access key             |
| `openai_api_key`      | `string \| null` | OpenAI API key (null if not configured) |

***

### Declaring injected parameters in the manifest

Add an `injected_params` array to each tool entry in `competency.manifest.json`. Only keys from the closed vocabulary above are accepted — anything else is a manifest validation error and will block installation.

```json
{
  "tools": [
    {
      "tool_name": "my_tool",
      "tool_description": "...",
      "injected_params": [
        { "key": "user_email" },
        { "key": "user_groups" },
        { "key": "tenant_id" },
        { "key": "msgraph_token", "scopes": ["Files.Read.All", "Mail.Read"] }
      ]
    }
  ]
}
```

The `scopes` field is only valid for `msgraph_token`. Every other key ignores it.

Declare only the keys your tool actually uses — the customer must consent to each one at install time, so unnecessary declarations create friction.

***

### Receiving injected parameters in your server

The orchestrator injects the resolved values into `params.arguments` before calling your MCP endpoint. Read them exactly like any other argument.

**Example — Python (FastAPI, MCP Streamable HTTP):**

```python
@app.post("/mcp")
async def mcp(req: Request):
    payload = await req.json()
    method  = payload.get("method")
    rpc_id  = payload.get("id")
    params  = payload.get("params") or {}

    if method == "tools/call":
        arguments = params.get("arguments") or {}

        # Injected by the orchestrator — always present if declared in the manifest
        user_email   = arguments.get("user_email")
        user_groups  = arguments.get("user_groups", [])   # list of strings
        tenant_id    = arguments.get("tenant_id")
        graph_token  = arguments.get("msgraph_token")     # Bearer token string

        # Normal LLM-supplied arguments
        invoice_text = arguments.get("invoice_text")

        # ... your logic here ...
```

**Do not** declare injected keys in your tool's `inputSchema` — they are stripped by the orchestrator before the LLM sees the schema. If you add them to `inputSchema`, the schema sent to the LLM will still omit them, but the mismatch may confuse schema validators on your side.

***

### Handling missing or null values

Injected values can be `null` in edge cases (unauthenticated context, optional config not set, etc.). Treat them defensively:

* `user_email`, `user_azure_id`, `user_display_name`: null if the orchestrator has no authenticated user in context (rare in production).
* `user_groups`: always an array, but may be empty.
* `msgraph_token`: null if no `IMsGraphDelegatedTokenProvider` is registered on the orchestrator (deployment configuration issue).
* `openai_api_key`: null if the customer has not configured an OpenAI key.

Return a clear error to the LLM if a required injected value is missing, rather than crashing silently.

***

### HTTP transport — Authorization header

For competencies using the `streamable-http` transport, the orchestrator can also send a static bearer token in the `Authorization` HTTP header. This is configured by the Dorg operator in the competency connection settings (`authorization_bearer`), and is separate from the injected parameter mechanism.

Use it to authenticate the orchestrator itself against your server (e.g. a shared secret). It is not a per-user token.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.dorg.pro/create-competency/develop-a-competency/mcp-server/injected-parameters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.