# AI Client Connection Guide (MCP)

How to connect an MCP-capable AI client to the AGENTIC STAR MCP endpoint. With the chat set, you ask an agent to do work; with the project set, you create and run projects, handle approval requests, and more. For the detailed specification of tools and scopes, see the [MCP API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/mcp-ref.md).

## What You Need

- The AI client you use (Claude Code, Codex, Cursor, VS Code, or Claude)
- To connect as a person: an application (Client ID) created in the Console
- To connect as a system integration: a system integration created in the Console, and its API key

## Install the Plugin (Recommended)

You can install the AGENTIC STAR plugin in Claude Code, Codex, and Claude. After installing it, ask "Connect to AGENTIC STAR", and it guides you through the connection.

| Included               | What it does                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| `agenticstar-connect`  | Guides you through connecting to the AGENTIC STAR MCP endpoint                           |
| `agenticstar-projects` | Creates projects, finds and fixes failures, handles approval requests, and reads results |

- The plugin does not include MCP connection settings. Set your Client ID or API key by following its guidance
- It is a different plugin from the Marketplace edition's. For the SaaS edition, use the plugin on this page
- Current version: `3.4.0`

[Download the plugin (agenticstar.zip)](https://developers.fd.agenticstar.tm.softbank.jp/en/plugins/agenticstar.zip)

**Claude Code**

In the folder where you extracted the zip, run the following (Claude Code 2.1.292 or later).

```bash
claude plugin install agenticstar --marketplace ./agenticstar
```

**Codex**

In the folder where you extracted the zip, run the following.

```bash
codex plugin marketplace add ./agenticstar
codex plugin add agenticstar@agenticstar
```

Codex reads the plugin's instructions with the shell. Use it with the shell available.

**Claude**

In claude.ai or Claude Desktop, open **Customize > Plugins**, select **Add > Upload plugin**, and choose the zip as it is.

## Choose How to Connect

| Who uses it                       | How to connect                                 | What to prepare in the Console     |
| --------------------------------- | ---------------------------------------------- | ---------------------------------- |
| A person (with their own account) | Sign in from the client                        | An application (Client ID)         |
| A system (system integration)     | Put a fixed API key in `Authorization: Bearer` | An API key of a system integration |

The MCP endpoint is shown below. Select the tool sets to use with `toolsets` (see [Tool Sets](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/mcp-ref.md#tool-sets-toolsets)).

```text
https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project
```

> **About the configuration examples**
>
> The settings on this page are examples for reference. How to configure a client can change between its versions. For the latest instructions, see each client's documentation ([Claude Code](https://code.claude.com/docs/en/mcp), [Codex](https://learn.chatgpt.com/docs/extend/mcp), [Cursor](https://cursor.com/docs/mcp), [VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers), [Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)). For other MCP clients, set the endpoint, Client ID, and redirect URI by following that client's documentation.

## Connect as a Person

### 1. Create an Application in the Console

Create it by following [Console Guide — Steps to Create an Application](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#steps-to-create-an-application).

- **Application type**: Select "Mobile / Native" (it has no Client Secret and signs in with PKCE)
- **Redirect URI**: Register the redirect URI of each client you use (see the table below)
- **Scopes**: Select `mcp:connect` and the scopes of the tools you use. The scope for each tool is in [MCP API Reference — Provided Tools](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/mcp-ref.md#provided-tools) (for example, `chat:exec` for the chat set, `project:read` to read projects)

| Client               | Redirect URI to register                                                              |
| -------------------- | ------------------------------------------------------------------------------------- |
| Claude Code          | `http://localhost:<port>/callback` (the port you pass to `--callback-port`)           |
| Codex                | The value you set in `callback_url` (for example, `http://localhost:<port>/callback`) |
| Cursor (desktop app) | `http://localhost:8787/callback`                                                      |
| VS Code              | `http://127.0.0.1/` and `https://vscode.dev/redirect`                                 |
| Claude               | `https://claude.ai/api/mcp/auth_callback`                                             |

- For redirect URIs on `http://127.0.0.1`, `http://[::1]`, or `http://localhost`, the port is not checked. If you register the URI without a port (for example, `http://localhost/callback`), you can sign in whatever port the client uses. If you register it with a port, only that port is accepted
- For clients that let you choose the redirect URI (such as `callback_url` in Codex), we recommend `127.0.0.1` over `localhost`
- If you registered `http://127.0.0.1:33418/` for VS Code earlier, add `http://127.0.0.1/` to the client

### 2. Configure the Client and Sign In

Replace `<client_id>` with the Client ID of the application you created.

**Claude Code**

```bash
claude mcp add --scope user --transport http \
  --client-id <client_id> --callback-port <port> \
  agenticstar 'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project'
```

Open `/mcp` in Claude Code and choose to authenticate `agenticstar`, or run `claude mcp login agenticstar`. The sign-in page opens in the browser.

**Codex**

Add the following to `~/.codex/config.toml`.

```toml
[mcp_servers.agenticstar]
url = "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project"

[mcp_servers.agenticstar.oauth]
client_id = "<client_id>"
callback_port = <port>
callback_url = "http://localhost:<port>/callback"
```

Run `codex mcp login agenticstar`. The sign-in page opens in the browser.

**Cursor**

Add the following to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json`).

```json
{
  "mcpServers": {
    "agenticstar": {
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project",
      "auth": {
        "CLIENT_ID": "<client_id>"
      }
    }
  }
}
```

Enable `agenticstar` in the MCP list on the **Customize** page in the sidebar, and continue when asked to sign in. A server written in the project's `.cursor/mcp.json` is available in chats started in that project.

**VS Code**

Add the following to `.vscode/mcp.json` in your workspace.

```json
{
  "servers": {
    "agenticstar": {
      "type": "http",
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project",
      "oauth": {
        "clientId": "<client_id>"
      }
    }
  }
}
```

Start the server from "MCP: List Servers" in the Command Palette. The sign-in page opens in the browser.

- To use the tools from chat, VS Code chat (GitHub Copilot) must be available
- Set **Session Target** in the chat input to **Local**. Other harnesses (such as Copilot) do not receive this configuration and cannot connect
- If an earlier sign-in remains, sign out from your VS Code account before trying again

**Claude**

1. Open the screen for adding a custom connector

   <!-- -->

   - Free, Pro, and Max plans: open **Customize > Connectors**, select **+ Add**, then **Add custom connector** (the Free plan allows one custom connector)
   - Team and Enterprise plans: an Owner opens **Organization settings > Connectors**, selects **Add**, then **Custom** (**Web**)

2. Enter a name and the endpoint URL above (with `?toolsets=chat,project`), then select **Continue**

3. On the next screen, check that **OAuth client** is set to **Use your own OAuth client**, and enter the Client ID (leave the secret blank). For AGENTIC STAR, **Authentication** and **OAuth client** are selected automatically. Select **Add**

4. On Free, Pro, and Max plans, select **Connect** and sign in to AGENTIC STAR in the browser that opens. On Team and Enterprise plans, after the Owner adds it, each member opens **Customize > Connectors**, selects the connector with the **Custom** label, clicks **Connect**, and signs in with their own account

By default, Claude asks for confirmation each time it uses a tool (deny, always allow, or allow once).

Claude connects to AGENTIC STAR from Anthropic's servers, not from the user's computer. The same connector works in claude.ai, Claude Desktop, and Cowork.

## Connect as a System Integration

1. Create it by following [Console Guide — System Integration Creation Steps](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#system-integration-creation-steps). Select `mcp:connect` and, depending on the operations you use, `project:read` and `project:run`, and set the [project restriction](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#project-restriction)
2. Issue an API key on the system integration's detail page (see [Console Guide — API Key](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#api-key))
3. Set `Authorization: Bearer <API key>` in the client. You don't need to get a new token

**Claude Code**

```bash
claude mcp add --scope user --transport http agenticstar-system \
  'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project' \
  --header "Authorization: Bearer <API key>"
```

**Codex**

Put the API key in the environment variable `AGENTICSTAR_API_KEY`, and add the following to `~/.codex/config.toml`.

```toml
[mcp_servers.agenticstar-system]
url = "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project"
bearer_token_env_var = "AGENTICSTAR_API_KEY"
```

**Cursor**

```json
{
  "mcpServers": {
    "agenticstar-system": {
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project",
      "headers": {
        "Authorization": "Bearer <API key>"
      }
    }
  }
}
```

**VS Code**

```json
{
  "inputs": [
    { "type": "promptString", "id": "agenticstar-api-key", "description": "AGENTIC STAR API key", "password": true }
  ],
  "servers": {
    "agenticstar-system": {
      "type": "http",
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project",
      "headers": {
        "Authorization": "Bearer ${input:agenticstar-api-key}"
      }
    }
  }
}
```

Set **Session Target** in the chat input to **Local**. Servers that use `${input:…}` are not passed to other harnesses (such as Copilot).

A system integration can use the five operations of the project set (`list` of `project_read`, `get` of `run_read`, and `start_run`, `fire_trigger`, and `cancel_run` of `project_run`) and `list_personas` of the chat set (use `toolsets=chat,project` for `list_personas`). It can only work with projects within its project restriction. Claude has no way to connect as a system integration.

## Use It Safely

- **Operations that write**: When you let the AI create, change, or delete projects, or decide approval requests, use the client's permission settings so that you can check each operation before it runs (Claude Code asks for permission every time before it decides an approval request. Claude lets you set permissions per tool. For other clients, see the client's documentation)
- **Read-only use**: For read-only use, create an application whose scopes are only `mcp:connect` and `project:read`
- **API key**: Treat an API key as a secret, the same as a Client Secret. Don't paste it into chats or documents
- **If credentials leak**: When people connect, delete the application in the Console. For a system integration, delete the API key or disable the system integration. It can take up to about 1 minute to take effect (see [Console Guide — If Credentials Leak](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#if-credentials-leak))

## Troubleshooting

- **Tool sets**: Without `toolsets`, only the chat set is available. Specify `project` to use the project set
- **Redirect URI mismatch**: If the sign-in page shows a redirect URI error, check that the client's redirect URI matches the one registered in the Console (for Claude Code and Codex, the port)
- **Missing scopes**: When you call a tool without the required scope, a tool error returns the scope needed and what to do next. For a person's application, add the scope in the Console and sign in again
- **System integration scope**: A system integration can only work with projects within its project restriction
- **Rejected for a system integration**: `This endpoint is not available to client credentials` (403) is returned when a system integration calls an operation it cannot use. To use that operation, connect as a person
- **Front-end protection (WAF)**: Depending on the input, a request can be stopped by the front-end protection. In that case the HTTP status is `403`, and in the JSON body `error.code` is `waf_blocked`. When there is a reference number, it is in `error.reference`
- **When the tools change**: When an AGENTIC STAR update changes the tools, reconnect (in Claude Code, `/mcp`; in Claude, refresh the tool list from the connector's menu)

## See Also

- [MCP API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/mcp-ref.md) — Specification of tools, scopes, and errors
- [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md) — Getting tokens and scopes
- [Console Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md) — Creating applications, system integrations, and API keys
- [Connection Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/connection-guide.md) — Choosing between REST, MCP, and A2A
