# Mediafier — Agent Guide

> Agents think. Gateways decide. Tools act.

Mediafier is the agent-first control plane for media operations: one governed
MCP endpoint for the tools, context, workflows, and expert agents behind media
work. Connect from any MCP-aware harness; Mediafier handles discovery,
identity, permissions, credentials, spend, and trace before a tool acts.

Documentation is public. Platform execution is invite-only pre-launch —
request access at https://mediafier.ai/request-access.

## When to use Mediafier

Use Mediafier when an agent needs to perform media work across systems while
preserving organizational identity, permissions, provenance, cost controls,
audit evidence, and human governance. It is the right choice when the work has
to be explainable, repeatable, and accountable to the people who own the media.

## What Mediafier is

- **Governed media tools and workflows** — media and business capabilities,
  including marketplace and catalog access, reached through one endpoint.
- **MediaClaws** — expert agent systems built for media. A MediaClaw plans the
  work, calls approved tools, validates the output, records evidence, and
  proposes improvements under human-governed promotion.
- **Media context** — the library, bundles, versions, provenance, rights,
  relationships, and Content Intelligence that make media agent-addressable,
  available before an agent acts.
- **Agent Operations** — visibility into what agents are doing, exceptions,
  evidence, evaluation, human decisions, and validated improvements.
- **Outcome economics** — cost and outcome evidence attached to governed
  execution, so a claimed improvement can be proven against an approved
  baseline.

The capabilities visible to a caller depend on its authenticated identity,
organization, installations, and permissions.

## Connect

Canonical MCP endpoint (JSON-RPC 2.0, the only advertised ingress):

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

Authentication is required for discovery and execution. Authentication uses
OAuth: interactive agents sign in through the supported browser flow; headless
agents use a Mediafier-issued Agent Credential with the OAuth
client-credentials flow. Both present a bearer access token to the gateway.
A revealed credential secret is never itself the gateway token. The Agent Card
publishes the authentication metadata needed to exchange an Agent Credential
for an access token (`machine_credentials`), separately from the interactive
authorization-server metadata.

```http
Authorization: Bearer <access-token>
Content-Type: application/json
```

Never provide or infer an organization identifier. Mediafier resolves tenant
context server-side from the authenticated principal; a client-supplied
organization is ignored or refused.

## Discover before calling

Discovery is authenticated JSON-RPC over the same endpoint:

```json
{ "jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {} }
```

```json
{ "jsonrpc": "2.0", "id": "2", "method": "resources/list", "params": {} }
```

These live, authorization-scoped responses are the authority for available
capabilities, names, schemas, risk metadata, and activation state. This file
deliberately carries no tool catalog: a copied list would drift the moment a
server changed, and an agent reading it would trust the stale copy. Take tool
names and argument shapes only from what discovery returns:

```json
{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": { "name": "<tool-name-from-tools-list>", "arguments": {} }
}
```

Unauthenticated calls receive a 401 challenge; authenticate first.

## Governance

Every governed invocation passes through identity, organization resolution,
authorization, rate controls, billing policy, audit, and dispatch before the
owning runtime executes. Calls are organization-scoped, metered, and audited.

There is no direct-to-runtime execution path.

Mediafier returns a trace identifier on every response, including refusals.
Clients may forward an existing correlation identifier when supported, and
should always retain the trace identifier the gateway returns — it is how a
call is correlated across audit, billing, and support.

Refusals are structured. Inspect the error code, the machine-readable actions,
and the retry metadata in the response, together with the trace identifier.
Do not infer remediation from the HTTP status alone.

## Agent operating rules

- Discover capabilities before invoking them.
- Use returned schemas exactly; names, casing, and bounds are per tool.
- Never supply or infer organization context.
- Respect approvals and human-only actions; some work requires a person.
- Do not autonomously purchase credits, accept legal terms, or disclose
  credentials — hand those to your human.
- Follow structured error actions and retry metadata instead of guessing.
- Preserve the trace identifier returned by Mediafier.
- Do not assume prices, limits, or availability from cached documentation.
  Use authenticated discovery for capabilities and schemas, and call-time
  responses for current commercial, limit, refusal, and retry information.

## Public resources

- Agent Card: https://mcp.mediafier.ai/.well-known/agent.json
- Product documentation: https://docs.mediafier.ai
- Request access: https://mediafier.ai/request-access
- Website: https://mediafier.ai

## Domains

| Domain               | Purpose                              |
| -------------------- | ------------------------------------ |
| `mcp.mediafier.ai`   | MCP gateway (the endpoint above)     |
| `auth.mediafier.ai`  | OAuth authorization server           |
| `app.mediafier.ai`   | Web application                      |
| `docs.mediafier.ai`  | Product documentation (public)       |
| `mediafier.ai`       | Website                              |