AI Assistants and API Keys

An AI assistant such as Claude or ChatGPT can work inside one MetricPeek team through a connection the team approves. It reads the team's reports, posts, media and hashtag lists, and, where the connection allows it, drafts and publishes posts or spends the team's credits on new reports and searches. The connection uses the Model Context Protocol (MCP), so the assistant is added as a custom connector by pasting one address, and nothing has to be installed. Scripts, automations and agents that run on a server cannot sign in through a browser, so they use a team API key instead, with the same access levels and limits. This page covers connecting an assistant, creating a key, what both can do, what they cost, how to teach an assistant good habits and how to switch them off.

Before you start#

AI assistants are included on every plan, Free as well. They start switched off in every team, and only the team owner can turn them on.

The person connecting an assistant has to be a member of the team with a role that can publish, which means the Owner or an Editor. An Approver cannot connect one, and neither can a client who was only given access to a shared post or report.

A connection belongs to one person and works for one team. Somebody who works in two teams connects twice, once for each. A team can hold two connections for every member whose role can publish, so each of those members can have both Claude and ChatGPT connected at once. API keys have a separate limit of their own and never take an assistant's place.

API keys start on the Start plan and are not part of Free. The pricing page lists the plans that include them. Only the team owner can create one.

The assistant itself needs an account that accepts custom connectors. Claude adds them from Customize → Connectors, in the browser, in the desktop app and in Cowork. ChatGPT needs Developer mode for them. Whether ChatGPT offers it, and whether a connected server may make changes or only read, depends on the ChatGPT plan and on the workspace's settings, as OpenAI's help article explains. On Business and Enterprise, a workspace admin may need to allow Developer mode first.

Turn on API & MCP access for the team#

This step is for the team owner. Everybody else sees whether access is On or Off, and nothing to change. One switch covers assistants and API keys alike.

1. Switch the app to the team concerned, then open Settings and choose the API & MCP tab. The tab always shows the team currently open in the app.
2. On the API & MCP access card, turn on the switch next to the title. Access is on at once.
3. Choose the team's daily credit limit on the same card: 25%, 50% or 100% of the team's credits, or Custom for a number of credits. 25% is the default and carries a Default badge. The meter under the choices gives the limit in credits for today. The choice is saved as soon as it is made, and there is no button to press.

The daily credit limit covers what assistants and API keys spend, all of them together. What people spend in the app does not count towards it. How the limit is worked out is under Credits and limits.

Switching access off later asks for a confirmation first, then stops every assistant and every API key in the team on its next call. The connections and keys themselves are kept, and they work again as soon as the switch is turned back on.

Connect Claude#

These steps work the same in Claude in the browser, in the Claude desktop app and in Cowork, as Anthropic's help article describes. The server address comes from MetricPeek, where How to connect in Settings → API & MCP shows it with a button to copy it. On Claude Team and Enterprise, the owner of the Claude organization adds the connector first, as the end of this section explains. Claude Code connects with an API key instead, as its own steps under Connect a tool with an API key show.

1. In Claude, open Customize → Connectors.
2. Press + and choose Add custom connector.
3. Name it MetricPeek and paste the server address.
4. Leave the options as Claude detects them. Claude marks the first two as Detected, and the table shows what each option should read. One choice is to be avoided: Use Claude's published identity does not work with MetricPeek, because MetricPeek does not accept that kind of client identity, and the sign-in stops with an error.

   Option	Choose	Why
   Authentication	Sign in now	Each person signs in to MetricPeek and passes the consent screen before the assistant can use any tool. That screen is where the team and the access level are chosen.
   OAuth client	Register automatically	MetricPeek registers Claude as a client by itself during sign-in. Nothing has to be created or copied beforehand.
   Request headers	Leave empty	Signing in supplies everything the connection needs.

5. Choose Add. Claude opens MetricPeek in the browser.
6. Sign in if asked. On the consent screen, choose the team and what Claude may do, then press Allow access. Approve the connection walks through it.
7. Back in Claude, ask: "Which MetricPeek team are you connected to? Use whoami." The answer names the team and what the connection may do.

Claude's own plans decide who adds the connector and how many can be added:

• On Claude Team and Enterprise, only an owner of the Claude organization can add a custom connector, and it is added once for the whole organization: Organization settings → Connectors, Add, then Custom and Web, the server address, and Add again.
• Each member of that organization then opens Customize → Connectors, finds the connector the owner added, presses Connect and continues from step 6.
• Claude's Free plan allows one custom connector.

Connect ChatGPT#

These steps are for ChatGPT in a browser, which signs in to MetricPeek and passes the consent screen like Claude does. The server address, which ends in /mcp, comes from How to connect in Settings → API & MCP. The ChatGPT desktop app and Codex connect differently, with an API key, as Connect a tool with an API key explains.

1. In ChatGPT, open Settings → Security and login and turn on Developer mode, which ChatGPT marks as an elevated risk.
2. Open the Plugins page at chatgpt.com/plugins, press + and choose Create app. That choice is in the menu only once Developer mode is on.
3. Enter a name, for example MetricPeek, and a short description, paste the server address and choose Create.
4. Sign in when ChatGPT opens MetricPeek.
5. On the consent screen, choose the team and what ChatGPT may do, then press Allow access. Approve the connection walks through it.
6. In a new chat, choose Developer mode from the + menu, select MetricPeek and ask: "Which MetricPeek team are you connected to? Use whoami."

Approve the connection#

The consent screen is where a connection is first shaped, so it is worth reading top to bottom rather than pressing the button at the bottom.

1. The top card names the application and the address it returns to. When the sign-in returns to claude.ai or chatgpt.com, the card names Claude or ChatGPT after that address. Any other application is named in quotes, with a note that the name comes from the application itself and only the return address was checked, so a familiar name on its own proves nothing.
2. Choose a team. One team is already selected: the only one available, otherwise the team currently open in the app, otherwise the first on the list. Teams where connecting is not possible right now are shown greyed out, each with its reason. Switching teams in the app later changes nothing about the connection.
3. Choose an access level. Read only reads the team's data. Drafts adds Create and edit drafts, which also covers hashtag lists and media, and nothing it does goes public. Full adds Publish and schedule posts and Spend the team's credits. The list under the levels marks each of the four as included or Not included. Full is selected when the screen opens.
4. At Full, a Daily credit limit appears for this connection, in credits a day: 50, 100, 250 or Custom, which takes any whole number from 1 to 100,000. 100 is the default and carries a Default badge. Ticking No separate limit under the choices gives the connection no limit of its own, so only the team's daily limit applies to it. A number above the team's limit is kept as it was typed, and the connection is always stopped by the lower of the two. At the other levels the connection cannot spend credits at all.
5. Name in Settings → API & MCP shows the name the connection will carry, made of the assistant and the team. Rename changes it.
6. Press Allow access. Cancel leaves nothing behind.

The access level and the daily credit limit can be changed later, in either direction, with Change access in the connection's ⋮ menu in Settings → API & MCP, with the app switched to the team the assistant is connected to. Only the person who made the connection can change it. The change applies from the connection's next call, and nothing it already did is undone.

Connect a tool with an API key#

The ChatGPT desktop app, Codex, Claude Code, Cursor and other tools that run on a computer or a server connect with an API key rather than by signing in. MetricPeek only completes a sign-in that returns to claude.ai, claude.com or chatgpt.com, while these tools return to an address of their own, usually on the computer itself (localhost), so their sign-in cannot finish. The key comes first.

Only the team owner can create a key, and creating one needs the Start plan or a higher one. The API key tab of How to connect has its own Create API key button, and Create a key describes the same steps from the API keys card. The key is shown only once, and the same window offers the whole Authorization header, ready to copy. Other members ask the owner for a key, and the tab names who the owner is.

The key acts as the owner. A tool connected with it works in the key's team, with the access level and daily credit limit chosen when the key was created and without a consent screen, and everything it does is recorded under the owner's name. The key therefore goes into the tool's own settings or into an environment variable, and never into a chat, as Keeping a key safe explains.

Every tool below needs the server address from How to connect and the key. The API key tab lists the same tools, with the address already filled in.

ChatGPT desktop app#

1. In the ChatGPT desktop app, open the Plugins page, press Add and choose Add MCP server.
2. Fill in Connect to a custom MCP as the table below shows. The API key tab of How to connect lists the same values, with buttons to copy them.
3. Choose Save, then switch the server on.

With Headers, the app writes the key, as it was typed, into ~/.codex/config.toml in the home folder of the computer, the settings file it shares with Codex. That file must never be committed to a code repository or synced along with other settings files. Where the app can see environment variables, Bearer token env var is the better choice: it takes the name of a variable, for example METRICPEEK_API_KEY, never the key itself, and Headers then stays empty.

Codex CLI#

Codex CLI keeps its MCP servers in ~/.codex/config.toml, the same file the ChatGPT desktop app uses, so MetricPeek added in the app is already there. Otherwise, the address and the name of an environment variable holding the key go into that file, never the key itself:

[mcp_servers.metricpeek]
url = "<server address>"
bearer_token_env_var = "METRICPEEK_API_KEY"

METRICPEEK_API_KEY is then set to the key in the shell that starts Codex, and /mcp in Codex shows metricpeek among its active servers. The API key tab of How to connect holds the same block, with the address already filled in. The syntax follows OpenAI's Codex documentation.

Claude Code#

1. Add the server in a terminal with the command below, where <server address> is the address from How to connect.
2. Set METRICPEEK_API_KEY to the key in the shell that starts Claude Code, then start Claude Code.
3. Run /mcp in Claude Code. The list shows metricpeek as connected.

claude mcp add --transport http metricpeek <server address> --header 'Authorization: Bearer ${METRICPEEK_API_KEY}'

The single quotes keep ${METRICPEEK_API_KEY} as it was written, so Claude Code's settings file holds the name of the variable, and Claude Code reads the key from the environment each time it connects. In double quotes, the shell puts the key itself into the command, and Claude Code then saves the key in ~/.claude.json in the home folder. The command adds MetricPeek for the project folder it is run in, and --scope user adds it for every project. The syntax follows Claude Code's MCP documentation.

Cursor#

Cursor reads its MCP servers from ~/.cursor/mcp.json in the home folder, for every project, and from .cursor/mcp.json in a project folder, for that project only. MetricPeek goes in as a remote server, with the key read from an environment variable:

{
  "mcpServers": {
    "metricpeek": {
      "url": "<server address>",
      "headers": {
        "Authorization": "Bearer ${env:METRICPEEK_API_KEY}"
      }
    }
  }
}

Cursor replaces ${env:METRICPEEK_API_KEY} with the value of that variable, so the file holds the name of the variable and never the key. For a remote server, the variable is set in the shell profile or in the system environment, because Cursor loads an environment file only for servers that run on the computer itself. Cursor is restarted after the file or the variable changes, and the server can then be switched on or off under Customize → MCPs. The syntax follows Cursor's MCP documentation.

Another tool#

Any other tool with an MCP client that reaches servers over Streamable HTTP connects with the same two values: the server address from How to connect, and an Authorization header whose value is Bearer followed by a space and the key. A tool without an MCP client sends the requests itself, as Use the key shows.

Check it worked#

Once the tool is connected, ask it: "Which MetricPeek team are you connected to? Use whoami." The answer names the key's team and what the key may do. A tool without a chat calls the whoami tool itself, with the tools/call method. An error in place of an answer is explained under When something looks wrong, which covers the 401, 403 and 429 answers a key can get.

What the assistant can do#

Every action needs a minimum access level, and each level includes everything in the one before it. What a connection may do is also never wider than the person's current role in the team allows, and that role is checked again on every call.

Full is the only level that publishes or spends. A connection at Drafts prepares posts, lists and media, and never makes anything public or spends a credit. Taking a scheduled post off the schedule only needs Drafts, because the post goes back to being a draft with its content kept.

Credits and limits#

Most of what an assistant does is free: reading reports, posts, lists and media, writing drafts, adding files, and publishing. Five actions spend the team's credits, and they show up in the Activity list under these names.

• create_report, a new profile or hashtag report
• refresh_report, fresh data for a report the team already has
• set_report_tracking, automatic refreshes on a schedule
• search_hashtags, a hashtag search
• download_profile_media, media from a public profile

Paid calls cost the same as they do in the app and come out of the team's wallet. Each paid tool states its price in its own description, so the assistant can quote it before acting, and every paid answer reports the credits charged and the balance left. Current prices are on the pricing page.

Several cases cost nothing, or give the credits back:

• Asking for a report the team already has, or one that is still being generated, returns that report without a charge.
• Repeating a hashtag keyword the team has already paid for, from the assistant or in the app, is served from stored data for as long as the team's data window on that search is open.
• An assistant that repeats the same paid request a few seconds later gets the first result back, not a second charge.
• A report whose generation fails, a refresh that could not fetch anything and a hashtag search that finds nothing are refunded. So is a profile download that fails because the profile does not exist, is private or could not be read.
• The next page of a profile's posts or reels costs half of the first page.
• Adding media, from a link, from the chat or through the upload page, uses the team's storage allowance, not credits.

Tracking is a repeated cost. While it is on, every automatic refresh charges the team, until tracking is turned off. Turning it on for a hashtag report also charges once straight away, and for a profile report it does not. Turned on by an assistant or an API key, a profile report's tracking still counts one refresh against the connection's and the team's daily credit limits until midnight in the team's timezone, although nothing is charged for it then, and turning tracking off again gives that back. For a hashtag report, the charge made straight away counts against both limits like any other paid call.

Paid calls are limited by credits. A call that charges credits can run as often as the team's balance and its daily credit limits allow, and the daily allowance of free calls does not count it. The per-minute limit and the limit on background jobs running at once apply to it as to any other call.

Free calls have a daily allowance. The tools that charge nothing, such as reading a report, listing posts, writing a draft or publishing, count towards a daily allowance of free calls. The allowance belongs to the team, so every assistant and API key in it draws on the same one. It is smallest on Free and grows with each plan, and the pricing page lists it for every plan. A paid tool that ended up charging nothing counts towards it as well, for example a report that was refunded in full, a hashtag search repeated from stored data, or a report the team already had. A refused call does not count. Four tools never count towards the allowance and keep answering after it is used up, so an assistant can find out why it was refused: which team and capabilities the connection has, the credit balance, the plan's limits and the status of a background job. Once the allowance is used up, the free tools are refused until midnight. The paid ones keep working, unless paid calls that ended up free have used up the allowance on their own.

Two daily credit limits sit on top of the wallet. One belongs to the team and covers what all its assistants and API keys spend together. The other belongs to each assistant and each key on its own, and is set on the consent screen, when the key is created, or later with Change access. An assistant or key set to No separate limit has no limit of its own, and only the team's limit applies to it. A paid call that would cross either limit is refused before anything is charged. Reaching a limit is not running out of credits, and the balance is left as it was.

How the team's limit is worked out. By default, the assistants and keys of a team may spend a share of what the team had at the start of the day, plus any credits added during the day, and never less than a small fixed floor, so a team low on credits can still work. On the API & MCP access card that default is the 25% choice, and the meter shows it in credits. Spending during the day does not lower the limit, so it stays the same until midnight, and a credit pack bought for the team in the afternoon raises it straight away. The owner can choose 50%, 100% or a custom amount instead, on the same card in Settings → API & MCP. 50% and 100% are worked out from the team's credits at the moment they are chosen and then stay at that number until the owner changes the limit, while the default follows the team's credits every day. Only what assistants and API keys spend counts towards this limit, and credits people spend in the app never use it up.

When the day starts again. Both credit limits and the allowance of free calls start again at midnight in the team's timezone.

Reaching a limit sends an email. When the team's assistants and keys reach the team's daily limit, or the team runs out of credits, the owner gets an email about it, at most once a day. When a single assistant reaches its own limit, the person who connected it gets an email, and when an API key does, the owner gets one, at most once a day for each assistant and key.

Bursts wait. An assistant that calls too many times within a minute is asked to wait a moment, rather than being allowed to use up the day in a burst. A team can also run only a few background jobs at once, such as new reports, hashtag searches and media downloads, and one more is asked to wait until one of them finishes.

Safety and control#

• One person, one team. The connection only ever sees the team chosen on the consent screen, and every credit it spends comes from that team.
• The role decides, every time. A person who loses the publishing role or leaves the team loses their connections at the same moment, without anybody having to remember to revoke them.
• Client approval still applies. A post waiting for the client's approval is refused by the publish, schedule and retry actions alike. Editing a post the client already approved sends it back to the client. How approval works is on Sharing with Clients.
• Network rules still apply. A post with blocking validation problems is refused, and so is a post beyond the team's monthly post allowance.
• Nothing is deleted. The assistant cannot delete reports, media, posts or drafts. Taking a post off the schedule keeps it as a draft.
• Text from other accounts stays labelled. Biographies, captions and comments written by the accounts being analysed are returned apart from the data and marked as content under analysis.

Revoking a connection. Open Settings → API & MCP in the team the assistant is connected to, find the connection under AI assistants, open its ⋮ menu, choose Revoke and confirm. The assistant stops working immediately, and connecting it again means going through the consent screen. The owner sees every connection in the team and can revoke any of them, optionally with a note. The member whose connection it was sees who revoked it, when, and the note, in their own settings.

When the plan changes. Every plan includes AI assistants, so moving to another plan, Free included, leaves the team's connections working. The allowance of free calls follows the new plan. API keys are different, and a move to Free suspends them, as When a key stops working explains.

API keys#

An API key lets a tool that cannot sign in through a browser work in one team. That covers scripts, n8n or Zapier workflows, and agents running on a server.

How a key differs from an assistant#

• A key belongs to the team, an assistant to a person. An assistant is connected by a member and approved with Allow access on the consent screen. A key is created by the team owner in Settings and works without a browser, a sign-in or a consent screen.
• A key acts as the owner. Its calls, and anything it creates, such as a draft, are recorded under the owner's name. It works only while that person is still the team's owner.
• The same access levels and limits. A key has the same three access levels as an assistant and reaches the same tools, listed in What the assistant can do. Paid calls cost the same, the same daily credit limits apply, and free calls come out of the same daily allowance the team's assistants use.
• A key needs Start or a higher plan. Assistants work on every plan, while API keys are not part of Free.
• One team, always. A key works in the team it was created in. Switching teams in the app changes nothing about it.

Create a key#

This is for the team owner.

1. Open Settings → API & MCP in the team the key is for. The API keys card sits under AI assistants.
2. Press Create API key. The dialog names the team the key will work in.
3. Fill in Name after the tool that will use the key, for example "n8n client reports". The list then shows what stops working if the key is ever revoked.
4. Under Choose an access level, pick Read only, Drafts or Full. A key starts at Read only, and Full carries a warning, because anything holding the key can then publish on the team's accounts and spend its credits.
5. At Full, set the key's own Daily credit limit, in credits a day: 50, 100, 250 or Custom, and the limit has to be above zero. 100 is the default. Ticking No separate limit under the choices gives the key no limit of its own, so only the team's daily limit applies to it. A limit above the team's is kept as it was typed, and the key is always stopped by the lower of the two.
6. Choose when the key Expires. Never is the default. The menu also offers a few fixed lifetimes, and Custom for a number of days.
7. Press Create key.

The Create API key button appears only when the plan includes API keys, which means Start or a higher plan, when access is switched on for the team, and the team has fewer active keys than it is allowed. Once that limit is reached, the card states it in place of the button. Revoked and expired keys stay in the list as a record and do not count towards the limit, while a suspended key does.

Copy the key, once#

Next the dialog shows Copy your API key, and this is the only time the key is ever shown. MetricPeek stores a fingerprint of the key and never the key itself, so nobody can display it again later.

1. Press Copy next to API key, or next to Authorization header for the whole header value, ready to paste.
2. Store the key where the tool keeps its credentials, or in a password manager.
3. Press Done.

While the key is on screen, the dialog closes only through Done. The close button, Escape and a click outside do nothing, so a stray click cannot lose the key. Under the key, two lines repeat what it may do and when it expires. A key closed before it was copied cannot be recovered, so it is revoked and replaced with a new one.

Use the key#

A key works from any tool that can send an HTTP request, and from tools with their own MCP client.

• The address. The How to use it box in the same dialog shows the server address, the same one How to connect gives for assistants. Requests go to it as POST.
• The header. The key goes in the Authorization header, after the word Bearer. A key sent anywhere else, in the address or in the body of the request, is refused as if it were missing.

This request asks for the list of tools. The address and the key sit in environment variables rather than being typed into the command.

curl -X POST "$METRICPEEK_MCP_URL" \
  -H "Authorization: Bearer $METRICPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The answer lists every tool with a description of what it does and which arguments it takes, and each paid tool states its price there. A tool is run with the tools/call method, its name and its arguments, as the Model Context Protocol describes. A tool with its own MCP client takes the address and the header and does this part itself, as Connect a tool with an API key shows for the ChatGPT desktop app, Codex, Claude Code and Cursor.

Repeating a call safely. Every tool that creates, changes, publishes or spends something takes an optional idempotency_key argument, a value the script picks for each request. A call repeated with the same key from the same connection within 24 hours, for example after a timeout, returns the first call's result instead of doing the work again, and a paid tool does not charge a second time. A different request gets a new key, and for search_hashtags the same key with a different query is simply a new, paid search. Without a key, a search repeated a few seconds later still returns the first search's job without a second charge, and a keyword the team has already paid for is served from stored data at no cost.

Who sees the keys#

• The owner sees every key in the team, with its access level, its daily credit limit, what it has spent today, when it was last used and when it expires. A key's ⋮ menu offers View activity, Change access and Revoke, and the owner's Activity card includes the calls the keys made.
• An Editor sees the same list, marked Managed by the owner, without the menu and without what each key spent today. The keys' calls do not appear in an Editor's Activity card.
• An Approver does not see the card at all.

A key that expires within the next week shows its expiry date in amber.

Revoke a key#

Open the key's ⋮ menu, choose Revoke and confirm with Revoke key. Anything using the key stops working immediately, and this cannot be undone. The key stays in the list as Revoked, with who revoked it and when. Only the owner can revoke a key.

The owner can change a key's access level and daily credit limit later, in either direction, with Change access in its ⋮ menu, and the change applies from the key's next call. The expiry date cannot be changed. A key that needs a different one is replaced. The new key is created first, the tool is switched over to it, and the old key is revoked last, so the tool is never left without a working key.

When a key stops working#

• Access is switched off. While API & MCP access is switched off for the team, every key is refused. The keys are kept and work again once the switch is back on.
• The plan changes. When the team moves to a plan without API keys, which today means Free, the team's keys are marked Suspended, with a note and a link to Billing. They are kept as they are and start working again by themselves when the plan includes API keys once more. The team's AI assistants keep working through the change.
• The key expires. On its expiry date the key is marked Expired and stops working. An expired key cannot be extended, so a new key takes its place.
• Ownership is transferred. Handing the team to a new owner revokes every key the previous owner created, at the moment of the transfer. Those keys would spend the team's credits within limits the new owner never agreed to, so the new owner creates the keys the team still needs. A key is also revoked on its next call if the person who created it is no longer the owner for any other reason.
• MetricPeek support paused it. The key is marked Suspended with a note saying so, and support can explain why.

Keeping a key safe#

A key opens the team to whatever access level it was given, to anyone who holds it.

• Never paste a key into a chat, a chat with an AI assistant included. An assistant normally connects through its own consent screen, and a key given to the ChatGPT desktop app, Codex, Claude Code or Cursor belongs in the header or environment variable settings of its MCP server, never in a message.
• Never commit a key to a code repository or put it in a shared document. It belongs in the tool's credential store, an environment variable or a password manager.
• Never put a key in an address. Addresses end up in server logs and browser history, and MetricPeek refuses a key sent that way.
• Give a key only what it needs. A key that only reads reports stays at Read only, and a key for a one-off job can be given an expiry.
• Revoke a key that may have leaked at once, then create a new one. A revoked key never works again, whoever holds it.

Things to ask it#

Assistants work best with a plain request that names the account, the network and the outcome. These all work with the tools described above.

• "Which MetricPeek team are you connected to, and what are you allowed to do there?"
• "List our Instagram profile reports and summarise the three with the highest score."
• "Create a profile report for @examplebrand on TikTok and tell me the best time to post once it is ready."
• "Search Instagram hashtags for vegan baking, then put the best Niche and Rising ones into a new list called Vegan baking."
• "Read our default brand voice, write a caption for the photo at this link and save it as a draft for our Instagram and Facebook accounts."
• "Put the photos I attached into our Media Library in this order and make an Instagram carousel draft from them."
• "Check that draft for problems on each network, then schedule it for Friday at 18:00."
• "Which of our posts failed last week, and why? Retry the accounts that failed."
• "Our Instagram connection stopped working. Give me a link to reconnect it."
• "How did our TikTok account perform last month, and which content format did best?"

A request that needs an access level the connection does not have is refused with a reason, and the assistant usually passes that reason on.

Teach your assistant#

A connector gives an assistant MetricPeek's tools, and a skill teaches it how to use them well. MetricPeek publishes its own skill, a short set of instructions the assistant reads before it works in a team. The skill teaches habits rather than access: it has the assistant ask whoami first, so it knows the team and what the connection may do, ask before it publishes anything, and quote the price from a paid tool's own description before it spends credits. It changes nothing about what the connection may do, and the access level, the credit limits and client approval apply as before.

The skill comes in three files:

• metricpeek.zip, the skill for Claude and ChatGPT
• instructions.txt, the same guidance as plain text, for a chat app that does not take skills
• metricpeek-agent.zip, a skill for coding agents, which connect with an API key

Claude. Open Customize → Skills, press +, choose Create skill, then Upload a skill, and pick metricpeek.zip. Skills are available on every Claude plan and need code execution to be switched on. The text of instructions.txt also works as the instructions of a Claude project, where it applies to every chat in that project.

ChatGPT Business, Enterprise and Edu. Open Plugins → Skills, choose Create, then Upload from your computer, and pick metricpeek.zip. ChatGPT scans an uploaded skill before it is used.

ChatGPT Plus and Pro. Skill uploads are offered on the plans above. On Plus and Pro, the text of instructions.txt goes into the instructions of a project, and it applies to every chat in that project.

Claude Code and Cursor. One command installs the agent skill:

npx skills add <MetricPeek address>/skills/metricpeek-agent.zip

Here <MetricPeek address> is the server address from How to connect without /mcp at the end. The same command, with the address already filled in, is also in the API key tab of How to connect. The agent still needs its own API key, kept in an environment variable and never in the project's files, as Connect a tool with an API key shows.

Reading the results#

Settings → API & MCP shows the team currently open in the app, so checking an assistant or a key starts with switching to its team, which the assistant names when asked. The tab holds four cards.

API & MCP access carries the owner's switch and the team's daily credit limit. The owner also sees a meter of the credits every assistant and API key in the team has spent since midnight, against that limit. Spending in the app does not move the meter. Other members see whether access is On or Off.

AI assistants lists each connection with the person who made it, its access level, its own daily credit limit or no spending, and when it was last used. A member sees their own connections and the owner sees all of them. Each one carries a status:

• Active, working now within its limits
• Suspended, kept but refused on every call until the reason shown under it is gone
• Revoked, switched off for good, with who revoked it and when

API keys lists the team's keys with the same statuses, plus Expired, and is described in Who sees the keys.

Activity lists what assistants and API keys did in the team: the source, the tool, what it touched, what it cost or Free, and when. It filters by source and by tool, and View activity in the menu of a connection or a key jumps straight to its calls. The card states how long calls are kept. As with connections, a member sees their own calls and the owner sees everybody's, the keys' calls included.

Common questions#

Does the Free plan include an assistant?#

Yes. Claude or ChatGPT can be connected on Free, read the team's data, write drafts, publish, and spend the team's credits on reports and searches, with the same daily credit limits as on any other plan. What Free leaves out is API keys, which start on the Start plan. The daily allowance of free calls is also smaller on Free, and the pricing page compares it across plans.

Why does the assistant ask before it publishes?#

Every tool describes itself to the assistant, including whether it only reads or changes something outside the conversation. Publishing, scheduling and most paid actions are marked as changes, and Claude and ChatGPT typically use that marking to ask for a confirmation before running them. A connection below Full cannot publish at all, whatever the assistant is asked. The MetricPeek skill adds the same habit as an instruction.

Can a photo be sent to the assistant straight from the chat?#

Yes. How the file travels depends on the chat app, and it always lands in the team's Media Library.

• ChatGPT can hand the files attached to a message straight to MetricPeek where the app supports it, and they are then imported into the Media Library in the order they were attached.
• Where the files are not handed over, as in Claude, or in ChatGPT where that is not supported, the assistant opens an upload window in the conversation if the app can show one, and always gives the address of a MetricPeek upload page as well. The upload page works in every case.
• The upload page opens in the browser for the person who made the connection, signed in to MetricPeek. Files are added in the order they are arranged on the page, and once the page says they are in, telling the assistant that they are uploaded is enough for it to find them.
• An upload that was not finished can be replaced with a new link. The old page then says a newer upload replaced it and points to the new one.

Uploads use the team's storage allowance, not credits, and a file that is already in the Media Library is used as it is rather than stored twice. The accepted file types and the size limits are stated in the assistant's answer.

Can the assistant buy credits or connect a new social account?#

Credits are bought in the app only, and a purchase goes to the team the app has open at the time, when the buyer owns that team, otherwise to the buyer's personal team. Credits for the team the assistant is connected to are therefore bought by that team's owner after switching the app to that team, and the assistant names the team it works for when asked. The assistant can also say how many credits are left, if the person's role may see the balance.

A social account is connected in the app too, and the assistant can give the link that gets there. The link opens Integrations ready to connect a new account on the chosen network, or to reconnect an account whose connection stopped working. It opens the app in the connection's team, so the account lands in the right team even when the browser was last working in another one. In that case a page asks before switching teams. Nothing is connected until the person confirms it in the browser. The link works only for the person who connected the assistant, signed in as themselves, and only while that connection is active. This is better than opening Integrations by hand, which opens in whatever team the browser was last working in. The assistant cannot disconnect an account.

Can one assistant work for several teams?#

Not through one connection. A connection works for the team picked on the consent screen, and a second team needs a second connection.

Which timezone does "Friday at 18:00" mean?#

The team's own timezone. A time given without a UTC offset is read in that timezone, and the answer states it both there and in UTC.

Can a client connect an assistant to review posts?#

No. Connecting requires membership in the team with a role that can publish. Clients review work through a share, as described on Sharing with Clients.

What this does not do#

• It does not delete anything. Reports, media, posts and drafts stay, and a cancelled scheduled post becomes a draft.
• It does not pick up files by itself. A file reaches the Media Library when the chat app hands it over, when it is dropped into the upload window or on the upload page, or when it is found at a public link.
• It does not buy credits or change the plan. Those stay in the app, and credits for the assistant's team are bought with the app switched to that team.
• It does not connect or disconnect a social account by itself. It can give a link to connect or reconnect one, and the person confirms it in the app.
• It does not use MetricPeek's own AI writing tools. The assistant writes captions itself, using the brand voice as guidance, and cannot edit the brand voice.
• It does not run the side-by-side profile comparison from the app. It reads reports one at a time and compares them itself.
• It does not work across teams. One connection serves one team.
• It does not raise its own access level, and it does not skip client approval or the network rules.
• It does not show an API key a second time, and it does not change a key's expiry after the key is created.

When something looks wrong#

The consent screen says no team can connect an assistant. It gives a reason for each team. AI assistants are switched off for this team means the owner has not turned access on yet. Your role in this team cannot publish means the person is an Approver in that team. This team already has as many assistants connected as its plan allows means every place is taken, two for each member who can publish, and revoking a connection nobody uses frees one.

ChatGPT has no Developer mode. ChatGPT keeps it under Settings → Security and login, not with its plugins. Not every ChatGPT plan or workspace offers it, as OpenAI's help article explains, and on Business and Enterprise a workspace admin may need to allow it first. Claude can be connected to the same MetricPeek team instead.

The assistant says it may not spend credits. Either the connection is below Full, or the person's role in the team may not spend them. The first is fixed with Change access in the connection's ⋮ menu, by the person who made the connection, in Settings → API & MCP of the team the assistant is connected to.

The assistant says a daily credit limit was reached. The team still has its credits. The call would have crossed the connection's own limit or the team's, and the message says which one and where it is changed. Both start again at midnight in the team's timezone. The owner can raise the team's limit on the API & MCP access card of the team the assistant is connected to, for example to 50% or 100%. A connection's own limit is raised with Change access in its ⋮ menu, by the person who made the connection, or by the owner for an API key, and No separate limit there leaves only the team's limit. A profile report's tracking switched on by an assistant or a key earlier the same day also counts towards both limits, as Credits and limits explains.

The assistant says the daily allowance of calls is used up. The free calls of the day are spent, across every assistant and API key in the team. Reading, drafting and publishing wait until midnight in the team's timezone, while paid actions such as a new report or a hashtag search keep working. A larger allowance comes with a higher plan, as the pricing page shows.

The assistant says it has to wait. Too many calls arrived within a minute, or the team already has as many background jobs running as it may. It is a pause, not a failure, and the next call a little later goes through.

A call is refused with an idempotency key code. idempotency_key_reused means the same key was already used from this connection within the last 24 hours for a call of this tool with different arguments, so nothing was done and the new request needs a new key. A paid call can also get it, with the reason charge_key_spent, when its key already paid for an earlier call whose result is no longer kept, and then nothing is charged or started and the call is sent again with a new key. idempotency_key_in_progress means the first call with that key is still running, so nothing was started twice, and the same call a few seconds later returns its result.

A call fails with internal_error. Something failed on MetricPeek's side rather than in the request, and part of the call may already have taken effect. The result is checked first, in the app or with the tool that reads it, before anything is repeated. A call that writes or spends is repeated only with the same idempotency_key it was first sent with, where the tool takes one, so it is not done or charged twice.

A post is refused as waiting for approval. The client has not decided yet. Nothing the assistant does can publish it before then, and the post's detail page in the app shows what it is waiting for.

An upload page shows a page not found error. An upload page works only for the person who made the connection, or for an API key, the person who created the key. Anybody else, a teammate included, gets the same page not found error as an address that never existed, so a link passed on reveals nothing. Signing in as that person opens it.

The upload page says the link has expired. Upload links stay open for a limited time, which the page states, and it lists the files that arrived before it closed. Asking the assistant again gives a new link.

A file on the upload page shows Not added. The reason is under the file, and dropping the right file finishes the upload. When the assistant described the files in advance, only exactly those files are accepted, matched by their content rather than by their name.

A connect link says This link no longer works. The connection it came from, an assistant or an API key, has ended or is paused, or the account no longer needs reconnecting, for example because it was reconnected in the meantime. Asking for a new link where this one came from fixes the first case, and Open Integrations on the same page leads to the accounts without a link. A link opened by anybody other than the person the connection belongs to gets a page not found error, because the link only ever works for that person.

A connection shows Suspended. MetricPeek support paused the service for the team, and support can explain why. The connection is kept and starts working again once the pause is lifted.

A connection shows Revoked. It was switched off for good, by its owner, by the team owner, or automatically when the person's role or membership changed. The row shows who and when. Connecting again goes through the consent screen.

A request with an API key gets 401. The key is missing, mistyped, revoked or expired, or it was sent somewhere other than the Authorization header. All of these get the same answer on purpose, so a response never tells a stranger which keys exist. The API keys card of the key's team shows whether the key is still Active, and a revoked or expired key is replaced by a new one.

A request with an API key gets 403. The key was recognised but may not act for the team right now, and the error field of the answer names the reason. mcp_disabled_for_team means API & MCP access is switched off for the team. plan_lapsed means the plan no longer includes API keys, which happens after a move to Free. connection_suspended means MetricPeek has paused the key or the service for the team. ownership_lost means the person who created the key is no longer the owner, and the key is now revoked.

A request with an API key gets 429. Either the same wrong key was tried too many times within a minute, or one key sent too many requests within a minute. The Retry-After header gives the number of seconds to wait. A script that keeps retrying a wrong key is the usual cause of the first.

Done was pressed before the key was copied. The key cannot be shown again. It is revoked from its ⋮ menu and replaced with a new one.

There is no Create API key button. Only the owner can create keys, and other members see who manages them. For the owner, the card says what is missing instead: a plan without API keys, such as Free, access switched off for the team, or the team's limit of active keys reached. Revoking a key nobody uses frees a place.

Anything else, or the same problem twice, is worth sending to support with the name of the connection and roughly when it happened.