> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/connect/agent-first-access.md).

# Agent-First Access (CLI + MCP)

Code-first access from any agent platform, harness, or pipeline through the CLI and the MCP endpoint.

> **Code-first, callable from any agent platform, any harness, any IDE.** Mediafier shows up as native tools in whatever orchestrator your team is already running.

Agent-first access is Mediafier's primary surface. Every capability ships as a CLI command and an MCP tool. Model-neutral. Orchestration-neutral. The single gateway enforces auth, organization context, rate limiting, billing, and audit before any tool runs... so the security team reviews one enforcement chain, not forty per-tool integrations.

***

## Two ways in

### CLI

```bash
npm install -g @mediafier/cli
```

That installs the Mediafier CLI into the local environment. From there, every shipped capability is reachable as a CLI command — composable with shell scripts, CI jobs, or any local automation. The CLI uses the same identity, organization context, and billing rails as the MCP path.

**Discover the command vocabulary.** The first safe step on a fresh install is discovery: `mediafier commands list` prints the curated, stable command vocabulary offline (no token, no network), and `mediafier commands list --remote` lists the live partner commands available to your organization. Both are read-only — execution goes through the family nouns (`tools`, `mediaclaw`, `jobs`, …). See the [CLI reference](/connect/cli-reference.md) for the full command set.

### MCP

The canonical public ingress is:

```
POST https://mcp.mediafier.ai/mcp
```

It is callable from any MCP-aware agent harness. Identity is proved via a bearer token issued through the standard authentication flow; organization context is server-derived from that token. Clients never set tenant headers themselves. (An advanced scoped per-server form exists for harnesses that need a single-server session — see [MCP Access](/connect/mcp-access.md).)

***

## What a tool call looks like

Every tool call follows the same shape regardless of which family owns the tool:

1. The agent picks a tool from the discovery surface (a governed resource the planner reads).
2. The CLI or MCP request is sent to the gateway.
3. The gateway runs the deterministic enforcement chain (Identity → Org → Authorization → Rate → Billing → Dispatch).
4. The gateway routes the call to the runtime that owns the tool.
5. The runtime executes; the response carries the trace ID so the call is correlatable end-to-end.

If any step in the chain fails, the gateway returns a structured error envelope — including the same trace ID — and the runtime never sees the call.

***

## What you get

| Capability             | What it does for the agent                                                                                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Discovery**          | The agent reads a governed list of available tools, with input schemas, descriptions, and capability hints — without integrating against internal systems. |
| **Identity**           | Auth0 issues the bearer token; the gateway resolves the principal server-side.                                                                             |
| **Org isolation**      | Tenant context is derived from the authenticated identity. Cross-tenant calls are not possible from a client.                                              |
| **Billing**            | Calls are metered against an organization's credit ledger. Out-of-credits is signaled deterministically; the agent can re-plan or notify a human.          |
| **Audit**              | Every governed call — allowed or refused — produces an immutable audit row, correlated by trace ID.                                                        |
| **Schema enforcement** | Tool input schemas are validated before execution. The agent never reaches a runtime with malformed arguments.                                             |

***

## Trace IDs everywhere

Every response — refusals included — carries an `X-Trace-Id` header, and error envelopes repeat it as `trace_id`. That ID is the single piece of information needed to reconstruct what happened across identity, billing, runtime, and audit logs. Customer support runs on it. Internal incident triage runs on it.

***

## What an agent-first integration gives a security review

A security team auditing an agent-first integration sees one answer: every tool call goes through the same governed gateway, every action is metered, every action is audited, every action carries a trace ID.

That uniformity is the point. The security review evaluates one enforcement chain — "agents talk to one gateway, the gateway decides, the platform executes" — instead of one chain per tool integration. The same chain holds whether the agent is in a CLI, an IDE plugin, a CI job, or a Slack-triggered runbook.

***

## Where to go next

| If you're…                              | Read next                                                                           |
| --------------------------------------- | ----------------------------------------------------------------------------------- |
| Setting up your first connection        | The in-product **Get Started** flow at `app.mediafier.ai/get-started`               |
| Wanting the gateway internals           | [The Gateway](/platform/gateway.md)                                                 |
| Studying discovery                      | [Governed Resources & Discovery](/platform/governed-resource-substrate.md)          |
| Connecting a tool from your own systems | [MCP Access](/connect/mcp-access.md)                                                |
| Publishing a new MCP server             | [Publishing to Mediafier's Marketplace](/partners/publishing-to-the-marketplace.md) |