# Service accounts and machine access

Connect an agent or automation to the Load Factor MCP server without a browser sign-in, using a read-only service account with the OAuth client-credentials grant or a single bearer token.

People connect Claude, ChatGPT and Claude Code to Load Factor by signing in with Google. An agent that runs unattended, such as a scheduled analyst workflow, cannot complete that sign-in. For those, a Load Factor admin creates a **service account**: a read-only account for one agent that connects with a client ID and a client secret instead of a person's sign-in. If the agent's platform can store only one secret, the admin can issue a [single bearer token](#single-bearer-token) instead.

> [!NOTE]
> Service accounts are created by Load Factor admins. If you need machine access for an agent, ask your Load Factor admin; the secret is handed over through your platform's secret store, never by e-mail or chat.

## What a service account can do

- **Read only.** It can call the read-only tools listed in [MCP tools](https://loadfactorenergy.com/developers/tools): queue projects and developers with their confidence and evidence, companies and SEC company intelligence, power plants, PPAs and buyers, deals and news, grid and market data, Load Factor Insights, the data catalog and Load Factor Demand. Any tool added later stays unavailable to service accounts until it is reviewed. Resources and prompt templates are not offered to service accounts; every one has a tool that returns the same data.
- **No exports, no contact lists, no CRM or mail, no admin.** Contact details are withheld from every answer.
- **Its own permissions.** It sees the markets and detail its user type allows, and every answer carries the same confidence levels, record links and caveats as for a person.
- **No sign-in of any kind.** A service account has no password and cannot sign in to the Load Factor web app or connect through Google sign-in. Its credential works only on the MCP server, and never opens a web session.

## For admins: create, mint, rotate, revoke

Everything happens in the Load Factor admin panel under **AI Connectors (MCP) → MCP Access → Service accounts**.

### Step 1: Create the service account

Choose **New service account** and give it an address for the agent, for example `analyst-agent@yourcompany.com`, and a name. It gets the read-only agent user type, and MCP access is switched on for it.

### Step 2: Mint a credential

Choose **New credential** on the account (or **New bearer token**, see [Single bearer token](#single-bearer-token)). Give it a label (for example the platform it runs on) and, if you need to, a different expiry (default 180 days) or rate limits. The client ID and client secret appear **once**. Copy the secret straight into the agent platform's secret store; Load Factor keeps only a fingerprint of it and can never show it again.

### Step 3: Rotate it before it expires

Rotate it at once, too, if it may have been exposed. **Rotate** issues a new secret and stops the old secret, and every token made with it, immediately. Update the agent's secret store with the new one.

### Step 4: Revoke it when the agent is done

It stops within seconds. Blocking or retiring the account, or switching its MCP access off, stops it too.

Every create, mint, rotate and revoke is recorded with the admin who did it, and every request the agent makes appears under **MCP Activity**, labelled with the credential's name.

## For developers: connect with the client-credentials grant

The server follows the OAuth 2.0 client-credentials grant. Standard MCP clients that support it, such as the official MCP SDKs, need only the server URL, the client ID and the client secret.

> [!NOTE]
> The MCP endpoint keeps its current address, `mcp.loadfactorenergy.com`, for now; we'll announce any change in the [changelog](https://loadfactorenergy.com/developers/changelog).

1. Request an access token from `https://mcp.loadfactorenergy.com/token`, authenticating with HTTP Basic (or the `client_id` and `client_secret` form fields, not both).
2. Call the MCP server at `https://mcp.loadfactorenergy.com/mcp` with `Authorization: Bearer <access_token>`.
3. When the token expires (`expires_in`, at most an hour), request a new one the same way. There is no refresh token.

```bash title="curl"
# Read the credential from your secret store; never paste it into code, a ticket or a chat.
curl -s https://mcp.loadfactorenergy.com/token \
  -u "$LOADFACTOR_CLIENT_ID:$LOADFACTOR_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=mcp:read
# {"access_token": "<access token>", "token_type": "Bearer", "expires_in": 3600, "scope": "mcp:read"}
```

```python title="Python (FastMCP)"
import asyncio
import os

from fastmcp import Client
from fastmcp.client.auth import ClientCredentialsOAuthProvider

MCP_URL = "https://mcp.loadfactorenergy.com/mcp"

async def main():
    # The client fetches and renews the access token itself.
    auth = ClientCredentialsOAuthProvider(
        client_id=os.environ["LOADFACTOR_CLIENT_ID"],
        client_secret=os.environ["LOADFACTOR_CLIENT_SECRET"],
        scopes="mcp:read",
    )
    async with Client(MCP_URL, auth=auth) as client:
        me = await client.call_tool("whoami")
        stats = await client.call_tool("queue_stats", {"iso": "ERCOT", "group_by": "fuel"})
        print(me.content[0].text[:200], stats.content[0].text[:200])

asyncio.run(main())
```

Start with `whoami`: it confirms the account, its markets, its tool groups and its rate limits.

The only scope is `mcp:read`. A token request may leave `scope` out; `openid` and `email` are accepted and ignored, and anything else is refused with `invalid_scope`.

## Single bearer token

Some agent platforms can keep only **one** secret in their connection settings and send it as a header; they cannot run the client-credentials grant. For those, an admin chooses **New bearer token** on the service account instead of **New credential**. The token is shown once, with the same warnings.

- **When to use it.** Only when the platform cannot use the client-credentials grant. A client credential is safer: its access tokens last an hour at most.
- **How to send it.** Send it on every request to the MCP server at `https://mcp.loadfactorenergy.com/mcp` as `Authorization: Bearer <token>`. There is no token request and no renewal step. Bearer tokens start with `gibt_`.
- **Where it does not work.** It is not accepted by the token endpoint (`/token`), by the Load Factor web app or by its REST API. It never opens a web session.
- **Same rules.** It acts only for its service account, with the same read-only tools, rate limits, expiry (default 180 days, at most 365), logging and contact redaction as a client credential.

```bash title="curl"
# Read the token from your secret store; never paste it into code, a ticket or a chat.
curl -s https://mcp.loadfactorenergy.com/mcp \
  -H "Authorization: Bearer $LOADFACTOR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "whoami", "arguments": {}}}'
```

```python title="Python (FastMCP)"
import asyncio
import os

from fastmcp import Client

MCP_URL = "https://mcp.loadfactorenergy.com/mcp"

async def main():
    # A string auth value is sent as "Authorization: Bearer <token>" on every request.
    async with Client(MCP_URL, auth=os.environ["LOADFACTOR_BEARER_TOKEN"]) as client:
        me = await client.call_tool("whoami")
        print(me.content[0].text[:200])

asyncio.run(main())
```

> [!WARNING]
> A bearer token is more sensitive than a client credential. Anyone who holds it can read as the service account until it expires or is rotated or revoked, with no token request in between. Keep the expiry as short as the platform allows, rotate on a schedule (for example every 90 days), and rotate at once if it may have been exposed.

**Rotate** issues a new token and stops the old one on its next request; update the platform's secret store straight away. **Revoke** stops it on its next request. Blocking, locking or retiring the account, or switching its MCP access off, stops it too, and anything that ends the account's sessions also ends its bearer token: rotate it to resume.

An unknown, revoked or expired bearer token gets the same `401` (`invalid_token`) as any invalid token.

## Rate limits

Each credential has its own limits, on top of the [per-account limits](https://loadfactorenergy.com/developers/mcp/limits):

| Limit | Default | When you go over it |
|---|---|---|
| Calls per rolling minute | 30 | "Rate limit reached for this service credential (30 calls per minute). Retry after *N*s (retry_after=*N*)." |
| Calls per rolling 24 hours | 600 | "Daily limit reached for this service credential (600 calls per rolling 24 hours). Retry after *N* (retry_after=*N*)." |
| Token requests | 20 per 10 minutes | HTTP 429 with a `Retry-After` header. Reuse a token until it expires. |

A call over a limit is refused whole, with the wait in seconds; it never returns a partial answer. Paging through long lists quickly is paced like any account's, so request what you need with filters rather than walking every page.

## Errors when requesting a token

| Response | Meaning |
|---|---|
| `401 invalid_client` | The client ID or secret is wrong, or the credential was revoked or has expired. |
| `400 unauthorized_client` | The service account cannot be used right now (switched off, blocked or locked). Ask your Load Factor admin. |
| `400 invalid_scope` | The request asked for a scope other than `mcp:read`. |
| `400 invalid_request` | A parameter was sent twice, or both HTTP Basic and form credentials were sent. |

## Keeping the credential safe

- Keep the secret only in your agent platform's secret store. Never put it in source code, a repository, a log, a document or a chat.
- Use one credential per agent or platform, with a label that says where it lives, so you can rotate or revoke one without touching the others.
- Prefer a client credential to a bearer token whenever the platform supports the client-credentials grant.
- Rotate before the expiry date shown in the admin panel. If a secret may have been exposed, rotate or revoke it at once: the old secret and its tokens stop immediately.
- A leaked access token is read-only, limited to one service account, rate-limited, and expires within an hour. A leaked bearer token has the same limits but lasts until its expiry date, so revoke or rotate it at once.
