# First steps with evoMCP

> Create your first connection, link it to Claude, ChatGPT, Claude Code or Cursor, and see how human approval and the audit log work in practice.

# First steps with evoMCP

This guide takes you from installation to a first task done by an assistant. You need to have [installed the package](https://evoaddons.com/en/documentation/evomcp-install) and to be signed in to the administrator as a user who can manage evoMCP.

## 1. Check the warnings on the Connect tab

Open Components → evoMCP → Connect. At the top is the MCP server address, with a button to copy it. It looks like `https://your-site/mcp`.

Below it, the "Before connecting" block warns you if:

- the site does not use HTTPS (Claude and ChatGPT only connect to HTTPS addresses);
- the address is not public (localhost, an internal network or a test domain);
- the MCP server is disabled in the options;
- some active connections use approval "none";
- the advanced layer is on.

If everything is fine you will see "All set". \[PENDIENTE: screenshot of the Connect tab\]

## 2. Create a connection

A connection is the unit of access. It defines who acts, what it can touch and how much it can do.

1. Go to Components → evoMCP → Connections and click "New connection".
2. Fill in the name and choose the Joomla user. Tools run with that user's identity and permissions, and the connection can never do more than the user can. If the assistant will sign in through OAuth, choose the user who is going to authorise it.
3. If you like, set the expiry date, the monthly call quota and the allowed IPs (one per line).
4. Leave human approval on "Every write needs approval (recommended)".
5. Under "Permissions by component", choose the level for each area. A new connection starts with read access to content. Users, orders and leads stay off until you grant them.
6. Save. If the connection uses a token, the panel shows it once. Copy it now: the server stores only its SHA-256 fingerprint.

Only a Super User can grant the administration areas (users, extensions, configuration, system, the advanced layer and the generic entities and options) or bind a connection to another Super User. \[PENDIENTE: screenshot of the connection form\]

## 3. Connect an assistant

Pick your client. The first three connect through OAuth and ask you to sign in to your Joomla site.

### Claude (web and desktop)

1. Open Claude → Settings → Connectors.
2. Click "Add custom connector" and paste the server address.
3. Click "Connect". Your Joomla sign-in screen opens: sign in, choose the connection you want to share and the components you grant.
4. Go back to Claude. You can now ask it to work on the site.

### ChatGPT

1. Open ChatGPT → Settings → Connectors and turn on developer mode if asked. It depends on your plan.
2. Create a new connector, paste the server address and choose OAuth authentication.
3. Authorise with your Joomla user on the screen that opens.

ChatGPT's menus change often. If you cannot find these options, search the settings for "connectors" or "MCP".

### Claude Code

Run this in your terminal:

```
claude mcp add --transport http my-site https://your-site/mcp
```

Inside Claude Code, type `/mcp`, pick the server and choose "Authenticate". The browser opens with the Joomla sign-in screen.

### Cursor and other clients with a token

1. Create a token connection as in step 2 and copy the token (it starts with `evomcp_`).
2. Paste this JSON into the client's MCP settings and replace `TU_TOKEN`:

```
{
  "mcpServers": {
    "evomcp": {
      "type": "http",
      "url": "https://your-site/mcp",
      "headers": { "Authorization": "Bearer TU_TOKEN" }
    }
  }
}
```

Do not share the token or commit it to a repository. With Claude Code you can also use it instead of OAuth:

```
claude mcp add --transport http my-site https://your-site/mcp --header "Authorization: Bearer evomcp_…"
```

## 4. Try it out

Ask the assistant for something read-only, such as "list the article categories". If it sees no tools, ask it to run `evomcp_capabilities`: it tells you which permissions the connection has and which components exist but are not granted.

Then ask for a write, for example creating an article. In the default mode the assistant receives `pending_approval` and an identifier. The action has not run yet.

1. Open Components → evoMCP → Approvals.
2. Review the exact arguments of the action.
3. Click "Approve and run" or "Reject". On approval, the action runs as the connection's Joomla user.
4. The assistant checks the outcome with `evomcp_approval_status`.

An article created by an agent arrives as a draft, with its provenance recorded. Publishing it is a sensitive action and asks for approval.

Pending approvals expire after 24 hours, and a connection cannot have more than 50 pending at once. Each time an action is held, an email goes to the address set in the options or, if that is empty, to the site's address.

## 5. See what happened

- Audit: every call, rejected ones included, with connection, user, tool, result and latency. The panel tells you whether the hash chain is intact.
- Usage: calls, errors, average latency and volume per tool and per day.

From there, adjust permissions and modes to what you need. Every option is described in [Settings](https://evoaddons.com/en/documentation/evomcp-settings) and the tools are in the [reference](https://evoaddons.com/en/documentation/evomcp-reference).

---

https://evoaddons.com/en/documentation/evomcp-first-steps