# AI Client Connection Guide (MCP)

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

> **Before you start**
>
> MCP is available only in environments where an administrator has opened the MCP inbound endpoint. For a person to connect with their own account, the entrance for sign-in from an external tool must also be open ([API Setup Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md)).

## What You Need

- The AI client you use (Claude Code, Codex, Cursor, or VS Code)
- To connect as a person: the client ID of an external tool client that an administrator created in the authorization server console
- To connect as a system integration: a service account that an administrator created in the admin console (client ID and client secret)
- The address of the environment's external API entrance (`<your-domain>`) and of the authorization server's external entrance (`<auth-domain>`)

## Install the Plugin (Recommended)

You can install the AGENTIC STAR plugin in Claude Code and Codex. 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                                                            |
| `agenticstar-projects` | Creates projects with registered agents, finds out why runs failed, handles approval requests, and reads results |

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

[Download the plugin (agenticstar-mp.zip)](https://developers.fd.agenticstar.tm.softbank.jp/en/plugins/agenticstar-mp.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-mp --marketplace ./agenticstar-mp
```

**Codex**

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

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

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

## Choose How to Connect

| Who uses it                       | How to connect                                                                   | What to prepare                                 |
| --------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- |
| A person (with their own account) | Sign in with the client                                                          | An external tool client (client ID)             |
| A system (system integration)     | Put a token obtained with the Client Credentials flow in `Authorization: Bearer` | A service account (client ID and client secret) |

The MCP endpoint is as follows. Select the tool sets with `toolsets` ([Tool Sets](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/mcp-ref.md#tool-sets-toolsets)). To also call published workflows, add `published`.

```text
https://<your-domain>/api/v1/mcp?toolsets=chat,project
```

External tools do not choose scopes. When a person connects, the external tool can do what that person can do on the Main Screen.

> **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)). For other MCP clients, set the endpoint and client ID by following that client's documentation.

## Trying It in an Environment without a Domain

In an environment where no domain and certificate are set (the default state), the entrances use a self-signed certificate created by the product. External tools do not trust this certificate, so they cannot connect as is. To try connecting in the default state, do the following. The browser that opens for sign-in also shows a certificate warning.

### Claude Code

Start Claude Code with certificate verification turned off.

```bash
NODE_TLS_REJECT_UNAUTHORIZED=0 claude
```

With verification turned off, you cannot notice if the communication is intercepted or altered. Use it only while trying, and only for that launch.

### Codex

Get the certificate of the entrance and make Codex trust it.

1. Save the certificate of the entrance to a file (`<your-domain>` is the address of the external API entrance)

   ```bash
   openssl s_client -connect <your-domain>:443 -showcerts < /dev/null | openssl x509 > agentic-star.crt
   ```

2. Set the path of the saved file in the environment variable `CODEX_CA_CERTIFICATE`, and then start Codex (before `codex mcp login`)

   ```bash
   export CODEX_CA_CERTIFICATE="$PWD/agentic-star.crt"
   ```

The certificate changes when it is recreated (it is valid for 365 days, and it is also recreated when the entrance for sign-in from an external tool is opened). If you can no longer connect, get the certificate again.

### Cursor and VS Code

They cannot connect in this state. Cursor stays at "Connecting..." without showing the reason, and VS Code shows `unable to verify the first certificate`. Set up a domain and certificate before using them.

### Before Starting Regular Operation

Always set a domain and a certificate. Once they are set, neither setting is needed ([Domain Settings Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/domain-guide.md)).

## Connect as a Person

### 1. Prepare an External Tool Client

An administrator creates a client in the authorization server console by following [API Setup Guide — Creating an External Tool Client](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md#external-tool-client). Register `http://localhost/callback` and `http://127.0.0.1/callback` as the redirect URIs. Register `http://127.0.0.1/` as well when you use VS Code. The port is not checked, so you can choose any free port for the clients below.

### 2. Configure the Client and Sign In

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

**Claude Code**

```bash
claude mcp add --scope user --transport http \
  --client-id <client_id> --callback-port <port> \
  agenticstar 'https://<your-domain>/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://<your-domain>/api/v1/mcp?toolsets=chat,project"
scopes = ["openid"]

[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. Keep `scopes = ["openid"]`. It makes Codex request only `openid`, and AGENTIC STAR advertises only `openid`, so the sign-in works with this setting.

**Cursor**

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

```json
{
  "mcpServers": {
    "agenticstar": {
      "url": "https://<your-domain>/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://<your-domain>/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

## Connect as a System Integration

1. Create a service account in the admin console by following [API Setup Guide — Creating a System Integration](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md#service-account)
2. Get an access token from `https://<auth-domain>/api/v1/oauth/token` with the [Authentication Guide — Client Credentials flow](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md#token-retrieval)
3. Set `Authorization: Bearer <access_token>` in the client. When the token expires, get a new one in the same way and set it again ([Refreshing a Token](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md#token-re-acquisition))

**Claude Code**

```bash
claude mcp add --scope user --transport http agenticstar-system \
  'https://<your-domain>/api/v1/mcp?toolsets=chat,project' \
  --header "Authorization: Bearer <access_token>"
```

**Codex**

Put the token in the environment variable `AGENTICSTAR_TOKEN`, and add the following to `~/.codex/config.toml`.

```toml
[mcp_servers.agenticstar-system]
url = "https://<your-domain>/api/v1/mcp?toolsets=chat,project"
bearer_token_env_var = "AGENTICSTAR_TOKEN"
```

**Cursor**

```json
{
  "mcpServers": {
    "agenticstar-system": {
      "url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

**VS Code**

```json
{
  "inputs": [
    { "type": "promptString", "id": "agenticstar-token", "description": "AGENTIC STAR access token", "password": true }
  ],
  "servers": {
    "agenticstar-system": {
      "type": "http",
      "url": "https://<your-domain>/api/v1/mcp?toolsets=chat,project",
      "headers": {
        "Authorization": "Bearer ${input:agenticstar-token}"
      }
    }
  }
}
```

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 tools of the chat set, nine operations of the project set (`list` of `project_read`, `get`, `list_artifacts` and `get_artifact_content` of `run_read`, `get` of `execution_read` (status fields only), and `start_run`, `fire_trigger`, `cancel_run` and `cancel_execution` of `project_run`), and the tools of the published set. A system integration's token can work with all projects in this environment.

## 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. For other clients, see the client's documentation)
- **Tokens and secrets**: Treat access tokens and client secrets as secrets. Don't paste them into chats or documents
- **Stopping an external tool**: An external tool that has signed in does not stop when you sign out of the Main Screen. For how to stop it, see [API Setup Guide — Stopping an External Tool](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md#stop-external-tool)
- **If credentials leak**: Disable the service account or regenerate the client secret in the admin console ([API Setup Guide — If Credentials Leak](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md#if-credentials-leak))

## Troubleshooting

- **Calls return 401 whose `WWW-Authenticate` header has no `resource_metadata`, or 404**: The MCP inbound endpoint, or the entrance for sign-in from an external tool, is not open in this environment. Ask your administrator
- **Certificate errors**: See [Trying It in an Environment without a Domain](#self-signed)
- **Tool sets**: Without `toolsets`, only the chat set is available. Specify `project` for the project set, and `published` to call published workflows
- **Sign-in is refused**: Accounts waiting for approval and accounts whose email address is not confirmed cannot sign in from an external tool. Get the account approved first
- **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
- **When the tools change**: When an AGENTIC STAR update changes the tools, reconnect (in Claude Code, `/mcp`)

## See Also

- [MCP API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/mcp-ref.md) — Tool and error specifications
- [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md) — Getting tokens
- [API Setup Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md) — Creating external tool clients and service accounts
- [Connection Methods Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/connection-guide.md) — Choosing between REST, MCP, and A2A
