🔑Authentication

The MCP server accepts two kinds of credential. They are equivalent in what they can reach, they differ in how the credential gets there and how the project is decided.

Mode	Credential	Project
API key	A MetaCopier API key you created yourself, sent as a header	The project the key belongs to
OAuth	Your MetaCopier login, exchanged automatically for a short lived credential	The project in the URL, or the oldest project you own

---

Mode A: API key

Creating the key

1. Open the MetaCopier web app.

2. Go to Projects → API Keys.

3. Create a key for the project you want the assistant to work on.

4. Copy the key. It is shown once.

Give the AI its own key. Do not reuse a key that your EA, your website or a partner already uses. A separate key can be revoked without breaking anything else, and the audit log then shows exactly what the assistant did.

Sending the key

Either header works:

X-API-KEY: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

The second form exists because some MCP clients only offer a generic bearer token field. MetaCopier tells an API key and an OAuth token apart by their shape, so there is no ambiguity.

What the key may do

Exactly what the key itself may do, no more. That is decided by two things:

• The key's permission type, READ_ONLY or READ_WRITE.

• The key's access policy, which can restrict endpoints, account fields, IP addresses and CORS origins.

🔐Access Policy

An access policy is optional, and it applies to both modes. On an OAuth connection it is the policy of the project's AI Apps key that counts.

If you want an assistant that can look but not touch, the cleanest way is a READ_ONLY key. A read only endpoint is a second, independent layer you can add on top.

When to use this mode

• Your client cannot do OAuth.

• You are building your own agent or automation.

• You want a credential that is not tied to a person and does not expire.

• You want the access policy to do the fine grained restriction for you.

---

Mode B: OAuth

How it works

You never handle a token. The flow is:

1. Your AI host asks MetaCopier's MCP server what it needs. The server answers with a standard discovery document (RFC 9728) that names MetaCopier's identity provider.

2. The host sends you to the MetaCopier sign in page. You log in and approve the requested permissions.

3. The host receives an access token for the MCP server, and nothing else. That token is only valid for MetaCopier's MCP server, it cannot be replayed anywhere else.

4. On every request, the MCP server exchanges that token for a short lived MetaCopier credential, scoped to your project and narrowed to the permissions you approved. It lives for 60 minutes and is minted fresh, so there is nothing for you to renew.

The credential the MCP server uses internally is a child of a key called AI Apps, which MetaCopier creates in your project the first time an assistant connects. Revoking that key cuts off every AI connection to the project at once. See security and limits.

Scopes: what the assistant is allowed to do

When you approve the connection, the host asks for one or more of these:

Scope	Grants
mcp:read	Reading everything the underlying key may read: accounts, copiers, strategies, positions, history, reports, logs, news.
mcp:config.write	Changing configuration: creating and editing accounts, copiers, strategies, templates, dashboards, project features.
mcp:trading.write	Placing, modifying and closing trades. See trading with AI.

The rules are strict and enforced on MetaCopier's side, not by the assistant:

• Without mcp:config.write and without mcp:trading.write, the credential is read only. Every write is refused.

• Without mcp:trading.write, every trading endpoint is refused even if configuration writes are allowed. A conversation about copier settings cannot turn into an order by accident.

• A scope can only ever narrow what the underlying key may do. If the project's AI key is read only, mcp:trading.write changes nothing.

• On a project with more than 100 accounts, both write scopes are dropped and the credential is read only. See security and limits.

Grant mcp:trading.write only if you really want the assistant to trade. You can always reconnect later with more permissions.

Which project does OAuth use?

If the project is in the URL, that project is used:

https://ai.metacopier.io/p/{projectId}/mcp

If it is not, for example because your client cannot store a long URL, MetaCopier resolves the project from your account:

1. Only projects you own count.

2. Deleted projects are skipped.

3. White label projects are skipped, because they belong to another brand.

4. Of what remains, the oldest one is chosen.

5. If nothing remains, the connection fails with [PROJECT_NOT_FOUND].

With more than one project, always pin the project in the URL. The oldest project rule is a convenience for single project customers, not a selection you should rely on.

When to use this mode

• You are a person using ChatGPT, Claude or a similar assistant.

• You want the connection tied to your login, so it ends when your access ends.

• You want to approve permissions explicitly instead of managing key permissions yourself.

• You do not want a long lived secret sitting in a configuration file.

---

Comparison

Property	API key	OAuth
Setup effort	Create key, paste it	Paste the URL, sign in
Lifetime	Until you revoke it	Until you sign out or revoke access
Secret in a config file	Yes	No
Project selection	The key's project	URL, otherwise oldest owned project
Permission control	Key permission type plus access policy	Scopes, on top of the key permission and access policy
Works without a browser	Yes	No
Tied to a person	No	Yes