Connect an AI Agent to Meow Meow Scratch with MCP

Connect Codex or Claude Code to the hosted Meow MCP server, verify the connection with read-only tools and set a clear approval boundary before the agent changes anything.

MCP gives a compatible AI client schema-defined tools for discovering and managing your Meow Meow Scratch® resources. Instead of asking an agent to invent HTTP requests, you can let it call named tools with validated inputs and structured results.

What MCP adds

You
 │  natural-language request
 ▼
Codex or Claude Code
 │  schema-validated MCP tool call
 │  Authorization: Bearer [platform token]
 ▼
https://meowmeowscratch.com/mcp/
 │  authenticated Meow API request
 ▼
Apps, endpoints, records, dashboards and integrations

MCP changes the interface, not the underlying permissions. The agent can call only the tools the server exposes, and the platform token still determines which Meow resource routes are available.

MCP does not make an agent automatically trustworthy, add a draft mode to API resources or create a server-side human approval prompt. The client and the person operating it remain responsible for reviewing sensitive actions.

The trust boundary

Component	What it can see or do	Your responsibility
Agent client	Receives your prompt, discovers tools and submits tool calls	Use a trusted installation and an appropriate approval policy.
Agent Tools plugin	Adds the shared workflow instructions and MCP configuration	Review the source and release notes before installing updates.
Hosted MCP server	Receives the Bearer token and translates tool calls into Meow resource operations	Use the exact HTTPS endpoint and protect the token.
Meow API	Enforces authentication, validation, limits and resource permissions	Keep resources private unless anonymous access is intentional.

The hosted server cannot use API credentials to access identity, profile, platform-token management or billing subscription routes. Manage those in the web app.

Before you start

• A Meow Meow Scratch account
• Codex or Claude Code installed
• Permission to add a plugin or MCP server in your environment
• A platform token created under Account → Platform Tokens

Use a platform token for MCP because the tool set performs discovery across your account. An app API key is intentionally restricted to one app and is better suited to a Raspberry Pi, deployed device or single-app integration.

Never place the token in a repository, prompt, screenshot, MCP URL or committed configuration file. The configuration should contain only the environment-variable name.

For a temporary Bash, zsh, Git Bash or WSL session, enter the token without putting it in shell history:

read -s MEOW_PLATFORM_API_KEY
export MEOW_PLATFORM_API_KEY

Paste the token when the terminal waits, press Enter, then run the export command. Launch the agent from that same terminal so it inherits the variable.

Option 1: install the official Agent Tools plugin

This is the recommended setup. The official Meow Agent Tools repository packages both the hosted connection and the shared use-meow workflow.

Codex

codex plugin marketplace add meowmeowscratch/meow-agent-tools
codex plugin add meow-meow-scratch@meow-agent-tools

Start a new Codex thread after installation. Ask for a Meow task naturally, or run /mcp if the tools do not appear.

Claude Code

claude plugin marketplace add meowmeowscratch/meow-agent-tools
claude plugin install meow-meow-scratch@meow-agent-tools

Start a new Claude Code session or run /reload-plugins. Verify the server with /mcp. When explicit selection is useful, invoke the shared skill with:

/meow-meow-scratch:use-meow

This package supports Claude Code. It does not define a Claude.ai or Claude Desktop connector.

Option 2: configure only the MCP connection

Use manual configuration when you want the tools without the packaged workflow instructions.

Standalone Codex configuration

codex mcp add meow \
  --url https://meowmeowscratch.com/mcp/ \
  --bearer-token-env-var MEOW_PLATFORM_API_KEY

codex mcp list

The equivalent user configuration in ~/.codex/config.toml is:

[mcp_servers.meow]
url = "https://meowmeowscratch.com/mcp/"
bearer_token_env_var = "MEOW_PLATFORM_API_KEY"

Restart Codex or the Codex IDE extension after changing the configuration. For a project-specific setup, use the same table in a trusted project’s .codex/config.toml.

Standalone Claude Code configuration

Place this in the project’s .mcp.json:

{
  "mcpServers": {
    "meow": {
      "type": "http",
      "url": "https://meowmeowscratch.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${MEOW_PLATFORM_API_KEY}"
      }
    }
  }
}

Launch Claude Code from the shell where the variable is set, approve the project server and run /mcp. The file contains a variable reference—not the secret—so it can be reviewed without exposing the token.

Verify the connection without changing anything

Begin with an explicitly read-only prompt:

Use the Meow tools for a read-only connection check.

1. Call connection_status.
2. Call get_limits.
3. List my apps.
4. Summarise the result.

Do not create, update, delete, publish, revoke or reconfigure anything.

A successful check confirms that the MCP Authorization header contains a platform token without returning the token itself. The limits result shows current enforced capacity, and the app list proves the agent can perform authenticated discovery.

If the account has no apps, an empty list is still a valid result. Do not create a throwaway resource merely to prove that discovery works.

A safe first agent task

Separate discovery and planning from mutation. This prompt produces useful work without changing the account:

Inspect my Meow apps, endpoints, collection fields and dashboards.

Report:
- the existing structure;
- any duplicate or confusing slugs;
- remaining capacity relevant to a Weather Station project; and
- a proposed private app, endpoint and field design.

Do not make changes. Wait for my approval after presenting the plan.

After reviewing the plan, authorise one bounded change at a time. A good creation prompt names the resource, requires it to remain private and asks the agent to read it back:

Create only the private app described in the approved plan.
Do not create its endpoints yet.
Read the app back, report its slug and stop.

Creating a Meow resource is an immediate account change. The public resource MCP does not have a WordPress-style draft/publish stage. “Propose only” and “do not make changes” therefore need to be explicit when you want planning rather than execution.

Recommended tool workflow

1. Call connection_status.
2. Call get_limits before provisioning resources.
3. List apps and endpoints before creating or changing them.
4. Inspect endpoint and field schemas before writing data.
5. Resolve record, field, widget, webhook and key UUIDs through discovery; never guess them.
6. Require immediate human confirmation for destructive or sensitive operations.
7. Call the narrowest applicable tool.
8. Read the resource back and verify the result.
9. Return the consumer URL and relevant identifiers.

What the tools can cover

Family	Typical operations
Discovery	Connection status, enforced limits, field types, apps, endpoints, records and dashboards
Structure	Create, update and delete apps, endpoints and collection fields
Data	Create one record or a batch; inspect, update, delete, aggregate and export records
Integrations	Static payloads, proxies, webhooks, response encryption and request logs
Control panels	Create widgets, read configured state and write through widget UUIDs
Consumer views	Read public endpoints and records or open shared dashboards

Actions that need special care

Action	Why it matters	Safe expectation
Delete a resource or record	Data or structure may be difficult to recover	Show the exact target and request immediate confirmation.
Revoke a key	A running device or integration may stop working	Identify the key by discovered UUID and explain affected clients.
Change encryption	Clients may lose the ability to read responses	Explain the migration and key-handling consequences first.
Make an app or endpoint public	Data may become anonymously readable	Keep it private unless public access is explicitly approved.
Write through a dashboard	A bound device may react immediately	Confirm the dashboard, widget UUID and intended value.

The hosted MCP service does not insert its own human approval gate. Configure the client to ask for sensitive actions, and write prompts that define the allowed scope.

Troubleshooting

Symptom	What to check
401 or missing tools	Confirm MEOW_PLATFORM_API_KEY was exported before launching the client and contains an active platform token.
Redirect or negotiation failure	Use the exact URL https://meowmeowscratch.com/mcp/, including the trailing slash.
403	The requested route may be outside Meow resource access. Use the web app for account, token-management and billing operations.
429	The service allows 60 tool calls per token per minute. Stop polling and wait for the one-minute window.
Codex shows old configuration	Refresh or reinstall the plugin, then start a new thread and inspect /mcp.
Claude Code shows old configuration	Run /reload-plugins or start a new session.
Claude reports a missing variable	Export the variable before launching Claude Code, then inspect claude mcp list.
Plugin installed but MCP absent	Check client or workspace policy, then inspect /mcp and client debug output.

Security checklist

• The MCP URL uses HTTPS and ends with /mcp/.
• The token comes from MEOW_PLATFORM_API_KEY, not a file or URL.
• No token appears in source code, prompts, screenshots or logs.
• The installed plugin came from the official repository and its updates are reviewed.
• The first task is read-only discovery.
• New apps and endpoints remain private by default.
• Deletes, key revocation, encryption changes and sensitive writes require immediate approval.
• The agent verifies every mutation by reading the affected resource back.
• The workflow does not poll unchanged resources or exceed the 60-calls-per-minute limit.

Where to go next

Once read-only discovery works, use the agent to inspect an existing project and propose a small, private change. Keep the first mutation narrow, verify it immediately and expand the workflow only after the approval boundary behaves as expected.

See the official Meow MCP documentation for the current connection reference and the Meow Agent Tools repository for plugin source, manifests and the shared workflow.